\input texinfo @c -*- coding: utf-8; mode: texinfo; -*-

@settitle LilyPond Changes

@dircategory LilyPond -- the music typesetter
@direntry
* Changes: (lilypond-changes).          News since version 2.24.
@end direntry

@include en/macros.itexi

@documentencoding UTF-8
@documentlanguage en
@afourpaper

@macro manualIntro
This document lists changes and new features
in LilyPond version @version{} since 2.24.
@end macro

@lilyTitlePage{Changes}

@ignore

HINTS

* only show verbatim input for syntax/input changes

* try to be as brief possible in those cases

* don't try to provide real-world examples, they often get too big,
which scares away people.

* Write complete sentences.

* only show user-visible changes.

@end ignore

@warning{LilyPond releases can contain syntax changes, which may
require modifications in your existing files written for older
versions so that they work in the new version.  To upgrade files,
it is @strong{strongly recommended} to use the @command{convert-ly}
tool distributed with LilyPond, which is described in
@rprogram{Updating files with convert-ly}.  @command{convert-ly} can
perform almost all syntax updates automatically.  Frescobaldi users can
run @command{convert-ly} directly from Frescobaldi using
@qq{Tools > Update with convert-ly@dots{}}.  Other editing
environments with LilyPond support may provide a way to run
@command{convert-ly} graphically.}


@c Don't remove this top-level menu; it is needed to suppress automatic
@c generation of a `@detailmenu` block by `texi2any` up to version 7.2.
@menu
* Major changes in LilyPond::
* New for musical notation::
* New for specialist notation::
* Miscellaneous improvements::
@end menu


@contents


@node Major changes in LilyPond
@unnumbered Major changes in LilyPond

@itemize

@item
Margins are now wider by default following the general layout of
several publishers (and the recommendations of Elaine Gould).

In order to switch back to the previous settings (e.g., to keep
the same layout when upgrading an existing score to version
@version{}), add the following code:

@example
\paper @{
  top-margin = 5\mm
  bottom-margin = 6\mm
  top-system-spacing.basic-distance = 1
  top-markup-spacing.basic-distance = 0
  left-margin = 10\mm
  right-margin = 10\mm
  inner-margin = 10\mm
  outer-margin = 20\mm
  binding-offset = 0\mm
@}
@end example

@item
Instead of generating PostScript or SVG output by itself, LilyPond
can now use the Cairo library to produce its output.  This is
referred to as the @q{Cairo backend}, and can be turned on using
the @code{-dbackend=cairo} command-line option.  This works for
all output formats (PDF, SVG, PNG, PostScript), and brings speed
and rendering fidelity improvements in SVG output in particular.
However, keep in mind that this backend does not yet implement all
features of the default backends.  Among the features not
currently supported are PDF outlines, the
@code{-dembed-source-code} option for PDF, and the
@code{output-attributes} property for SVG.

@item
The distances between clefs and time signatures, together with the
distances between clefs and key signatures, are now calculated
differently.  As a consequence, you will get better spacing for
extra-wide clefs (like @code{\clef "GG"}) or extra-slim clefs
(like @code{\clef "petrucci-c3"}).

In the following image, both old and new positions are shown.
The percentage gives the width difference of clef plus time
signature and clef plus key signature, respectively.

@lilypond[quote]
diff =
#(define-music-function (percent) (string?)
  #{
     \once \override Score.TextMark.break-align-symbols = #'(clef)
     \textMark \markup {
                 \smaller \smaller { #percent \hspace #-0.5 "%" } }
  #})

musicA = {
  \override Score.Clef.space-alist.time-signature =
              #'(minimum-space . 4.2)
  \time 2/2 c'2
}
musicB = {
  \time 2/2 c'2
}

musicC = {
  \omit Staff.TimeSignature
  \override Staff.Clef.space-alist.key-cancellation =
              #'(minimum-space . 3.5)
  \override Staff.Clef.space-alist.key-signature =
              #'(minimum-space . 3.5)
  \key c \minor c'2
}
musicD = {
  \omit Staff.TimeSignature
  \key c \minor c'2
}

\markup \line {
  \override #'(baseline-skip . 10) \column {
    "clef + time sig"
    \vspace #-2.5
    "old"
    \vspace #-1
    \score { { \clef "treble" \musicA } }
    \score { { \clef "alto" \musicA } }
    \score { { \clef "bass" \musicA } }
    \score { { \clef "GG" \musicA } }
    \score { { \clef "varC" \musicA } }
    \score { \new PetrucciStaff {
               \clef "petrucci-c3" \musicA } }
  }

  \hspace #3

  \override #'(baseline-skip . 10) \column {
    "clef + time sig"
    \vspace #-2.5
    "new"
    \vspace #-1
    \score { { \clef "treble" \diff "-1.6" \musicB } }
    \score { { \clef "alto" \diff "+0.5" \musicB } }
    \score { { \clef "bass" \diff "0" \musicB } }
    \score { { \clef "GG" \diff "+17.9" \musicB } }
    \score { { \clef "varC" \diff "-5.6" \musicB } }
    \score { \new PetrucciStaff {
               \clef "petrucci-c3" \diff "-21.8" \musicB } }
  }

  \hspace #4

  \override #'(baseline-skip . 10) \column {
    "clef + key sig"
    \vspace #-2.5
    "old"
    \vspace #-1
    \score { { \clef "treble" \musicC } }
    \score { { \clef "alto" \musicC } }
    \score { { \clef "bass" \musicC } }
    \score { { \clef "GG" \musicC } }
    \score { { \clef "varC" \musicC } }
    \score { \new PetrucciStaff {
               \clef "petrucci-c3" \musicC } }
  }

  \hspace #4

  \override #'(baseline-skip . 10) \column {
    "clef + key sig"
    \vspace #-2.5
    "new"
    \vspace #-1
    \score { { \clef "treble" \diff "-1.5" \musicD } }
    \score { { \clef "alto" \diff "+0.5" \musicD } }
    \score { { \clef "bass" \diff "0" \musicD } }
    \score { { \clef "GG" \diff "+9.3" \musicD } }
    \score { { \clef "varC" \diff "-5.2" \musicD } }
    \score { \new PetrucciStaff {
               \clef "petrucci-c3" \diff "-23.5" \musicD } }
  }
}

\paper {
  indent = 0
}
@end lilypond

Note that, as before, the widest clef in a staff group determines
the horizontal position of all clefs in a system; this means, for
example, that a piano score containing a treble and a bass clef
doesn't change at all.

If you want to restore the previous default values for whatever
reason, add

@example
\override Staff.Clef.space-alist.time-signature =
            #'(minimum-space . 3.5)
\override Staff.Clef.space-alist.key-cancellation =
            #'(minimum-space . 3.5)
\override Staff.Clef.space-alist.key-signature =
            #'(minimum-space . 4.2)
@end example

@noindent
to your score.

@item
The LilyPond major mode for the GNU Emacs text editor provided by the
Emacs Lisp package @code{lilypond-mode.el} has been renamed from
@code{LilyPond-mode} to @code{lilypond-mode}.  The namespace prefix for
the package is changed to all lowercase @code{lilypond-} from
@code{LilyPond-}, meaning all its functions, variables, etc., now have
the all-lowercase prefix.  This change is made to comply with the
idiomatic Emacs naming convention, most importantly, having the major
mode name be the same as the package name that provides it.  Therefore,
this also makes it easier for new users to set up LilyPond in Emacs.

As a result, this will break some existing Emacs configurations
for end users.  However, it only requires minimal changes to the
Emacs initialization file.  Here's an example of setting up
@code{lilypond-mode} using the built-in @code{use-package} macro
in Emacs:

@example
(use-package lilypond-mode
  :ensure nil
  :mode "\\.\\(ly\\|ily\\)$")
@end example

@end itemize


@node Notes for source compilation and packagers
@unnumberedsec Notes for source compilation and packagers

This section is aimed at enthusiasts compiling LilyPond from source
and packagers preparing LilyPond for distribution.  If you are not
part of either group, you can skip over this section.

@itemize

@item
LilyPond now requires Guile version 3.0.7 or newer.  By default,
@file{.scm} files are byte-compiled.  If you don't want to do that
for whatever reason, add @code{BYTECODE=no} as an argument to
@command{make}.

@end itemize


@need 1500
@node New for musical notation
@unnumbered New for musical notation

@node Pitches improvements
@unnumberedsec Pitches improvements

@itemize

@item
The new @code{\approximatePitch} command creates notes of
approximate pitch.

@lilypond[quote,verbatim]
\relative c'' {
  e4 f g \approximatePitch c
}
@end lilypond

@item
Certain spurious change clefs have been fixed.

@lilypond[quote,verbatim]
{
  R1
  \clef treble
  R1
}
@end lilypond

@end itemize


@node Rhythm improvements
@unnumberedsec Rhythm improvements

@itemize

@item
The @code{\time} command now supports complex meters which
previously required @code{\compoundMeter}, though it requires a
slightly different syntax.  The @code{\compoundMeter} command has
been renamed to @code{\timeAbbrev}.

@lilypond[quote,verbatim]
{
  \time #'((2 2 2 3) . 8)
  \repeat unfold 9 c'8
}
@end lilypond

@item
The new @code{\submeasureBarsOn} command enables automatic bar
lines between the components of strictly alternating time
signatures (not shown), or where specified by setting the new
@code{submeasureStructure} context property or grouping the beats
in the optional argument to the @code{\time} command.

@lilypond[quote,verbatim]
{
  \submeasureBarsOn
  \time #'((3 4) (3 4) (4 3 4)) 25/16
  \repeat unfold 25 c'16
}
@end lilypond

@item
The new @code{\polymetric} command simplifies notating polymeter
with aligned measures by setting scaled metric properties in
contexts other than @code{Timing}.

@lilypond[quote,verbatim]
<<
  \new Staff {
    \scaleDurations 4/6 {
      \context Staff \polymetric \time 6,6,6 18/16
      \repeat unfold 18 c'16
    }
  }
  \new Staff {
    \time 3/4
    c'4 4 4
  }
>>
@end lilypond

@item
The default auto-beaming settings for 2/8 time have been changed
to allow beaming the full measure.

@lilypond
<<
  \time 2/8
  \new Staff \with { subdivideBeams = ##f } {
    <>^"subdivideBeams = ##f"
    \repeat unfold 2 e'8
    \repeat unfold 4 e'16
    \repeat unfold 8 e'32
  }
  \new Staff \with { subdivideBeams = ##t } {
    <>^"subdivideBeams = ##t"
    \repeat unfold 2 e'8
    \repeat unfold 4 e'16
    \repeat unfold 8 e'32
  }
>>
@end lilypond

@item
@code{\enablePolymeter} has been renamed to
@code{\enablePerStaffTiming} to avoid confusion because it is
recommended in only a subset of polymetric use cases.

@item
The @code{TimeSignature@/.time-signature} property replaces the
old @code{fraction} property.  The new property is more general
and can be overridden, which allows certain tricks without
overriding the @code{stencil} property.

@lilypond[quote,verbatim]
{
  \once \override Timing.TimeSignature.time-signature = #'(-1 . 12)
  R1
}
@end lilypond

@item
The @code{\time} command now accepts a rational number in the
numerator.  The @code{TimeSignature} grob and
@code{\compound-@/meter} markup function have new properties that
control the style of fractional parts.

@lilypond[quote]
{
  \override Timing.TimeSignature.nested-fraction-mixed = ##t
  \override Timing.TimeSignature.nested-fraction-relative-font-size = -5.5
  \override Timing.TimeSignature.nested-fraction-orientation = #'vertical
  \time #'(5/2 . 4)
  r2 r8

  \override Timing.TimeSignature.nested-fraction-mixed = ##t
  \override Timing.TimeSignature.nested-fraction-relative-font-size = -5.5
  \override Timing.TimeSignature.nested-fraction-orientation = #'horizontal
  \time #'(5/2 . 4)
  r2 r8

  \override Timing.TimeSignature.nested-fraction-mixed = ##f
  \override Timing.TimeSignature.nested-fraction-relative-font-size = 0
  \override Timing.TimeSignature.nested-fraction-orientation = #'horizontal
  \time #'(5/2 . 4)
  r2 r8
}
@end lilypond

@item
The @code{\time} command now accepts a rational number in the
denominator to support time signatures with a beat longer than a
whole note.

@lilypond[quote,verbatim]
{
  \override Timing.TimeSignature.denominator-style = #'note
  \time #'(4 . 1/2)
  e'\breve f' g' a'
}
@end lilypond

@item
The @code{TimeSignature} grob and @code{\compound-@/meter} markup
function now support number-over-note time signatures via
@code{denominator-@/style} and related properties.

@lilypond[quote,verbatim]
{
  \override Timing.TimeSignature.style = #'numbered
  \override Timing.TimeSignature.denominator-style = #'note
  \once \override Timing.TimeSignature.time-signature = #'(2 . 8/3)
  \time 6/8
  r4. g'8 8 8
}
@end lilypond

@item
@code{\slashedGrace} now prints slashed beams.

@lilypond[quote,verbatim]
{
  \slashedGrace { d'16 e' d' } c'1
  \slashedGrace { d16 e'' d' } c'1
}
@end lilypond

Use @code{beam::slashed-stencil} to slash arbitrary beams.  Set
@code{details.slash-side} to @code{RIGHT} to print the slash at
the right side of the beam.

@lilypond[quote,verbatim]
{
  \override Beam.stencil = #beam::slashed-stencil
  \cadenzaOn
  c'16^[ a' c'']
  c''^[ a' c']
  c'_[ a' c'']
  c''_[ a' c']
  \override Beam.details.slash-side = #RIGHT
  c'16^[ a' c'']
  c''^[ a' c']
  c'_[ a' c'']
  c''_[ a' c']
}
@end lilypond

Use the @code{over-beam-height}, @code{slash-slope},
@code{slash-side}, @code{slash-stem-fraction},
@code{slash-thickness}, and @code{slash-X-positions} subproperties
of the @code{details} property to customize the appearance of the
slash.

@item
It is now possible to right-align different types of bar lines.

@lilypond[quote,verbatim]
\new StaffGroup
  <<
    \new Staff { \textMark "default" b1 }
    \new Staff { b1 \section }
  >>

\new StaffGroup
  <<
    \new Staff
      { \textMark "right-aligned" b1 }
    \new Staff
      { b1
        \override StaffGroup.BarLine.right-justified = ##t
        \section }
  >>
@end lilypond

@item
Bar checks (@code{|}) now implicitly create contexts.  The
developers deem this unlikely to impact real-world scores.  Please
report a bug if you find a problem without an obvious workaround.

@item
The new @code{span-all-note-heads} option may be used to make
tuplet brackets span all note heads (not just the stems) as
recommended by Gould and Ross.

@lilypond[quote]
{
  \time 3/4
  \override TupletBracket.span-all-note-heads = ##t
  \tuplet 3/2
    {
      \tuplet 3/2
        {
          fis'8
          (
          e'8
          d'8
        }
      g'4
      f'4
      )
    }
  \tuplet 3/2
    {
      <c' d'>8
      a'8
      r8
    }
}
@end lilypond

@item
Automatic beam subdivision has been reworked.  Previously, many
imperfections could be found in the results of automatic subdivision of
many complex beaming patterns due to overreliance of the value of
@code{beatBase}.  Now, LilyPond can correctly subdivide most beaming
patterns and no longer uses the value of @code{beatBase} to limit beam
subdivision.  Simply setting @code{subdivideBeams} to @code{#t} now
automatically subdivides all intervals by default.  Three new
properties have been introduced to tune automatic beam subdivision:
@code{beamMinimumSubdivision},
@code{beamMaximumSubdivision} and @code{respectIncompleteBeams}.
@code{beamMinimumSubdivision} limits subdivision intervals the
same way as how @code{beatBase} previously did (reducing frequency of
subdivided beams). @code{beamMaximumSubdivision} limits the
number of beamlets removed at subdivisions in general.
@code{respectIncompleteBeams} limits the number of beamlets at
subdivisions where the remaining length would not complete the metric
value of the subdivision. Setting @code{beamMinimumSubdivision}
to the value of @code{beatBase} at all times, even when
@code{beatBase} implicitly changes, preserves old behavior.

@item
New @q{stacked} flag glyphs are available.  All flag elements of a
flag glyph have the same width but are vertically more compact.

Use @code{\flagStyleStacked} to access them; with
@code{\flagStyleDefault} you can switch back to the standard flag
style.

@lilypond[quote,indent=0\cm,ragged-right,staffsize=26]
Music = {
  d'8*1/128 d'16*1/64 d'32*1/32 d'64*1/16
    d'128*1/8 d'256*1/4 d'512*1/2 d'1024 s1024
  g''8*1/128 g''16*1/64 g''32*1/32 g''64*1/16
    g''128*1/8 g''256*1/4 g''512*1/2 g''1024 }

{
  \omit Staff.BarNumber
  \omit Staff.Clef
  \omit Staff.TimeSignature
  \autoBeamOff

  <>^"stacked" \flagStyleStacked \Music \break
  <>^"default" \flagStyleDefault \Music
}
@end lilypond

@item
The @code{TimeSignature} style @code{'single-digit} has been
renamed to @code{'single-number}.


@end itemize


@node Expressive mark improvements
@unnumberedsec Expressive mark improvements

@itemize

@item
The new commands @code{\chordSlur} and @code{\nonArpeggiato}
support creating vertical slurs and brackets without abusing the
@code{\arpeggio} command.

@lilypond[quote,verbatim]
{ <c' g'>\nonArpeggiato <c' f''>\chordSlur }
@end lilypond

@item
A new ornament, @code{bachschleifer}, is now available.

@lilypond[quote,verbatim]
{ b' g''\bachschleifer }
@end lilypond

@item
It is now possible to position @code{Script} to the left or right side of a
@code{NoteHead}.

@lilypond[quote,verbatim]
{ <c' g' c''\atRight \mordent e''>2 }
@end lilypond

@item
Hairpins in the style of Ferneyhough now support @dfn{al niente}
circles.

@lilypond[quote,verbatim]
{
  \override Hairpin.circled-tip = ##t
  \override Hairpin.stencil = #flared-hairpin
  b1\< b\> b\> b2 b\< b2 b\!
}
@end lilypond

@item
Two new variant glyphs for breathing signs are available:
@q{laltcomma} and @q{raltcomma}.  These glyphs represent the old
shapes of @q{lcomma} and @q{rcomma}, respectively, before changing
them to more common shapes.

@lilypond[quote,verbatim]
{
  \override BreathingSign.text =
    \markup { \musicglyph "scripts.raltcomma" }
  f'2 \breathe f' |
}
@end lilypond

@item
The wavy part of a @code{TrillSpanner} grob needs less vertical
space now.

@end itemize


@node Repeat improvements
@unnumberedsec Repeat improvements

@itemize

@item
The new music functions @code{\%} and @code{\*} serve as
abbreviations for @code{\repeat percent} and @code{\repeat
unfolded}.

@lilypond[quote,verbatim]
\%3 \*4 cis''4
@end lilypond

@item
@code{\repeat volta} alternative endings no longer create
invisible bar lines.  This may affect line breaking, horizontal
spacing, and @code{VoltaBracket} length where an alternative
begins or ends without a bar line.  In the case of an undesired
change, try adding @code{\bar ""} or another command that creates
a @code{BarLine} at that point.

@item
Using the new @code{printInitialRepeatBar} property, it is
possible to print a start repeat bar line, automatically, at the
beginning of the piece.

@lilypond[quote]
\fixed c'' {
  \set Score.printInitialRepeatBar = ##t
  \repeat volta 2 { c2 f }
}
@end lilypond

@item
The volta number position relative to the the volta bracket can
now be adjusted with the @code{volta-number-offset} property of
@code{VoltaBracket}.

@end itemize


@node Editorial annotation improvements
@unnumberedsec Editorial annotation improvements

@itemize

@item
Incipits may now be printed with various context types.  It also
got an optional argument to shift the incipit to the left.

@lilypond[verbatim,quote]
\score {
  <<
    \new Staff \with { instrumentName = "MensuralStaff" }
      {
        \incipit { c'4 d' }
        c'4 d' e' f' g'1
      }

    \new Staff \with { instrumentName = "KievanStaff" }
      {
        \incipit #2 \new KievanStaff { c'4 d' }
        c'4 d' e' f' g'1
      }
    \new Staff
      \with { instrumentName = "TabStaff" }
      {
        \incipit
          \new TabStaff
            \with { \magnifyStaff 0.5
                    \override InstrumentName.font-size = 6 }
            { c'4 d' }
        c'4 d' e' f' g'1
      }
  >>
  \layout {
    indent = 5\cm
    incipit-width = 2\cm
  }
}
@end lilypond

@item
Optional additional material can be enclosed in brackets that pass
through the staff with @code{\startOptionalMaterial} and
@code{\stopOptionalMaterial}.

@lilypond[quote]
{
  \startOptionalMaterial
  c'1
  \stopOptionalMaterial
}
@end lilypond

@item
The @code{FingerGlideSpanner} may now connect @code{StringNumber} and
@code{StrokeFinger} grobs.

@lilypond[verbatim,quote]
{
  \set strokeFingerOrientations = #'(down)
  b2 \glide -\rightHandFinger #1 \glide -2 \glide \5
  e'-\rightHandFinger #1 -2 \5
}
@end lilypond

@item
A new engraver, @code{Toe_heel_engraver} (enabled by default)
listens to the context variable @code{toeHeelStyle} to provide
styling options for the commands @code{\rtoe}, @code{\ltoe},
@code{\rheel}, and @code{\lheel}.

@lilypond[verbatim,quote]
music = { f'4\rtoe f'4\rheel f'4\ltoe f'4\lheel \bar "||" }

{
  \music            % #'default
  \set toeHeelStyle = #'standard    \music
  \set toeHeelStyle = #'reversed    \music
  \set toeHeelStyle = #'below       \music
  \set toeHeelStyle = #'circleheels \music
}
@end lilypond

If the engraver is enabled, these commands no longer behave like
normal @code{Script} grobs since they ignore direction changes
(i.e., @samp{^}, @samp{_}, and @code{\tweak direction} are
ignored).  If the need arises to position pedal marks
individually, the new, standard articulation commands @code{\toe},
@code{\vartoe}, @code{\heel}, @code{\varheel}, and
@code{\heelcircle} (accessing the new glyph
@code{scripts@/.pedalheelcircle}) should be used instead.

@lilypond[verbatim,quote]
{
  f'2\toe f'2\vartoe |
  f'2\heel f'2\varheel |
  f'1\heelcircle
}
@end lilypond

Removing the engraver makes @code{\rtoe} and siblings behave as in
previous LilyPond versions.

@item
Directly related to the previous item are four new,
articulation-like commands to indicate toe-heel and heel-toe
substitutions, @code{\ltoeheel}, @code{\rtoeheel},
@code{\lheeltoe}, and @code{\rheeltoe}.  They are influenced by
the @code{Toe_heel_engraver} in the same way as @code{\rtoe} and
siblings.  Toe and heel glyphs have been harmonized in size to
make these substitution marks look good.

@lilypond[verbatim,quote]
music = { f'4\rtoeheel f'4\rheeltoe
          f'4\ltoeheel f'4\lheeltoe \bar "||" }

{
  \music            % #'default
  \set toeHeelStyle = #'standard    \music
  \set toeHeelStyle = #'reversed    \music
  \set toeHeelStyle = #'below       \music
  \set toeHeelStyle = #'circleheels \music
}
@end lilypond

@item
@code{NoteName} grobs are now horizontally centered by default.

@end itemize


@node Text and font improvements
@unnumberedsec Text and font improvements

@itemize
@item
Triangular note heads have been added to the Emmentaler font.
They can be used by overriding @code{NoteHead@/.style} to
@code{arrow}.

@lilypond
\fixed c' {
  \omit Staff.Clef
  \omit Staff.TimeSignature
  \override NoteHead.style = #'arrow
  g4 2. | a4 2. | c'4 2. | d'4 2.
}
@end lilypond

@item
A new @code{\bar-line} markup command to print bar lines in text is now
available.

@lilypond[verbatim,quote]
\markup {
  \override #'(word-space . 2)
    \line {
      Examples
      \fontsize #-5 \translate-scaled #'(0 . 2) {
        \bar-line ":|."
        \bar-line ".|:"
        \bar-line ";!S!;"
        \bar-line "]{|}["
      }
    }
}
@end lilypond


@item
The syntax for customizing text and music fonts has been changed.
Instead of

@quotation
@verbatim
\paper {
  #(define fonts
     (set-global-fonts
       #:music "Name of music font"
       #:brace "Name of music brace font"
       #:roman "Name of serif font"
       #:sans "Name of sans-serif font"
       #:typewriter "Name of typewriter font"))
}
@end verbatim
@end quotation

or

@quotation
@verbatim
\paper {
  #(define fonts
     (make-pango-font-tree
       "Name of serif font"
       "Name of sans-serif font"
       "Name of typewriter font"
       factor))
}
@end verbatim
@end quotation

@noindent
the new syntax is

@quotation
@verbatim
\paper {
  property-defaults.fonts.music = "Name of music font"
  property-defaults.fonts.serif = "Name of serif font"
  property-defaults.fonts.sans = "Name of sans-serif font"
  property-defaults.fonts.typewriter = "Name of typewriter font"
}
@end verbatim
@end quotation

Unlike the previous syntax, the new syntax does not interfere with
font sizes, which should be set separately using
@code{set-global-staff-size} or @code{layout-set-staff-size}.

There is no @code{brace} key in the fonts alist; braces glyphs now
always default to the music font.  However, it is still possible to
override this by using an extra font family, as shown in this example
(which requires the LilyJAZZ font):

@quotation
@verbatim
\layout {
  \context {
    \Score
    \override SystemStartBrace.fonts.music = "lilyjazz"
  }
}

\new PianoStaff <<
  \new Staff { c' }
  \new Staff { c' }
>>

\markup \override #'(fonts . ((music . "lilyjazz"))) \left-brace #20
@end verbatim
@end quotation

Because @code{fonts} is simply a property, it is possible to
override it on a per-grob basis, e.g.,

@quotation
@verbatim
\layout {
  \override Score.SectionLabel.fonts.roman = "Custom font"
}
@end verbatim
@end quotation

This is preferable over the already existing @code{font-name}
property, since the latter makes commands such as @code{\bold}
ineffective, instead requiring @qq{Bold} to be included in the
@code{font-name} string.  Using @code{fonts} does not have such
effects.


@item
The @code{\lookup} markup command can now only be used for braces;
for other glyphs, use the @code{\musicglyph} command.  Instead of
@code{\lookup}, it is also generally recommended to use @code{\left-brace}.


@item
In markup, when a music font is used (such as for dynamic markings), a
glyph absent from the music font was previously rendered in a normal
text font. This is no longer the case; a warning about the missing glyph
is output instead.  In order to use a text font, use the @code{\serif},
@code{\sans}, or @code{\typewriter} markup commands.  For example:

@lilypond[verbatim,quote]
dolceP =
#(make-dynamic-script
  #{
    \markup {
      \serif \normal-weight dolce
      p
    }
  #})

{ c'\dolceP }
@end lilypond


@item
Small caps are now achieved by overriding @code{font-variant} to
@code{small-caps} instead of overriding @code{font-shape} to
@code{caps}.  Since @code{font-shape} is primarily for achieving
italics, this change makes it possible to use small caps and italics
at the same time.

@item
The @code{font-series} property is now more flexible and allows
the specification of values such as @code{semibold} and
@code{light} instead of only @code{normal} and @code{bold}.

The @code{medium} value is now an intermediate value between
@code{normal} and @code{bold} rather than an equivalent of
@code{normal}.  Accordingly, the @code{\medium} markup command has
been renamed to @code{\normal-weight}.


@item
The new @code{font-stretch} property allows the selection of a
condensed or expanded font.


@item
The text of a @code{VoltaBracket} grob, as set by @code{\override
Score.VoltaBracket.text = @dots{}} or @code{\set
Score.repeatCommands = @dots{}}, is no longer automatically
typeset in a music font; use the @code{\volta-number} markup
command on those parts that need to be.  For example, convert

@quotation
@verbatim
\set Score.repeatCommands = #'((volta "2, 5"))
@end verbatim
@end quotation

@noindent
to

@quotation
@verbatim
\set Score.repeatCommands =
  #`((volta ,#{ \markup {
                  \concat { \volta-number 2 , }
                  \volta-number 5 }
            #}))
@end verbatim
@end quotation


@item
In markup, fingerings (@code{\markup \finger}) and bass figures
(@code{\markup \figured-bass}) now get scaled along with normal text
when using @code{\fontsize}.

@lilypond[quote,verbatim]
myText = \markup {
  The fingering \finger { 5-4 } for a \figured-bass { 7 "6\\" } …
}

\myText
\markup\fontsize #6 \myText
@end lilypond

The previous behavior can be restored by setting the global variables
@code{legacy-figured-bass-markup-fontsize} and @code{legacy-finger-markup-fontsize}
to @code{#t}, respectively:

@lilypond[quote,verbatim]
#(set! legacy-figured-bass-markup-fontsize #t)
#(set! legacy-finger-markup-fontsize #t)

myText = \markup {
  The fingering \finger { 4-5 } for a \figured-bass { 5+ 6 } …
}

\myText
\markup\fontsize #6 \myText
@end lilypond


@item
For best clarity, the @code{\roman} markup command has been renamed to
@code{\serif}.  Likewise, to cancel a setting of the @code{font-family}
property to @code{sans} or @code{typewriter}, it should now be set
to @code{serif}, not @code{roman}.


@item
The @code{\text} markup command has been removed.  Instead, the
@code{\serif}, @code{\sans}, or @code{\typewriter} markup commands
should be used.  These commands used to set the font style
@emph{only if a normal text font was used} (not a musical font,
such as for dynamics), but now they @emph{both} set the font style
and make a normal text font used.


@item
The font size used by the @code{\volta-number} markup command has
been reduced to make it better fit with surrounding text.  At the
same time, the size for the volta bracket number (which uses
@code{\volta-number} for formatting by default) has been increased
by the opposite amount, thus compensating for the change in the
normal use case.

@item
Some glyphs like @q{one} or @q{accidentals.hufnagelM1} in the
Emmentaler font had overly large glyph bounding boxes due to a bug
in the font production chain.  This is fixed now; be warned,
however, that you might experience typesetting differences because
tighter bounding boxes often lead to tighter typesetting.

@item
New markup commands to print the textual representation of accidentals are
added:
@code{\text-doubleflat}, @code{\text-flat}, @code{\text-natural},
@code{\text-sharp}, @code{\text-doublesharp} and the general
@code{\text-accidental}.

@lilypond[quote,verbatim]
\markuplist \override #'(padding . 1) \table #'(-1 -1 -1 -1 -1 -1) {
  "Accidentals for text:"
   \text-doubleflat \text-flat \text-natural \text-sharp
   \text-doublesharp
  "Accidentals for music:"
  \doubleflat \flat \natural \sharp \doublesharp
}
@end lilypond

@item
The @code{\circle} markup command now listens to a @code{bbox}
property.  If set to @code{#t}, the bounding box of its argument
is used for the circle's diameter.

@lilypond[verbatim,quote]
\markup {
  \circle {
    \center-column { "short" "short" "very very long" }
  }
  \override #'(bbox . #t) \circle {
    \center-column { "short" "short" "very very long" }
  }
}
@end lilypond


@item
The @code{\tag} command is now allowed in markup environments.  New
markup commands are added for filtering (@code{\keep-with-tag}
and @code{\remove-with-tag}) and for inserting markups
(@code{\push-to-tag}, @code{\append-to-tag} and @code{\replace-with-tag})
in markup context or from music context (@code{\pushToTagMarkup},
@code{\appendToTagMarkup} and @code{\replaceWithMarkup}).

@lilypond[quote,verbatim]
test = \markup {
  \tag #'a a
  \tag #'b b
  c
}

music = \relative {
  c'^\test c c c
}

\keepWithTag #'a \music
\removeWithTag #'a \music
\pushToTagMarkup #'a push \music
\appendToTagMarkup #'a append \music
\replaceWithTagMarkup #'a replacement \music

\markup { \keep-with-tag #'a \test }
\markup { \remove-with-tag #'a \test }
\markup { \push-to-tag #'a push \test }
\markup { \append-to-tag #'a append \test }
\markup { \replace-with-tag #'a replacement \test }
\markup { \keep-with-tag #'a \score { \music } }
@end lilypond

@item
The two new markup commands @code{\pad-x-left} and
@code{\pad-x-right} behave similar to @code{\pad-x} but apply
horizontal padding on one side of the markup only.


@end itemize


@node New for specialist notation
@unnumbered New for specialist notation

@itemize

@item
For consistency with other ancient clefs, five new mensural clefs
are available: @code{"mensural-f2"}, @code{"mensural-f3"},
@code{"mensural-f4"} (same as @code{"mensural-f"}),
@code{"mensural-f5"}, @code{"mensural-g1"}, @code{"mensural-g2"}
(same as @code{"mensural-g"}).

@item
The default time signature and accidental style in a
@code{PetrucciStaff} context is now the same as in
@code{MensuralStaff}.

@item
White mensural ligatures now support some rare ligatures
(semibreves alone or in the middle),
and allow tweaks to show some non-necessary stems.

@lilypond[quote,ragged-right,verbatim]
\score {
  \relative {
    \set Score.timing = ##f
    \set Score.measureBarType = #'()
    \override NoteHead.style = #'petrucci
    \override Staff.TimeSignature.style = #'mensural
    \clef "petrucci-c4"
    \[ a1 g f e \]
    \[ a1 g\longa \]
    \[ \tweak left-down-stem ##t a\breve b
       \tweak right-down-stem ##t g\longa \]
    \[ \tweak right-down-stem ##t b\maxima
       \tweak right-up-stem ##t g\longa \]
  }
  \layout {
    \context {
      \Voice
      \remove Ligature_bracket_engraver
      \consists Mensural_ligature_engraver
    }
  }
}
@end lilypond

@item
The use of the file @file{gregorian.ly} is deprecated.  While
still distributed for backward compatibility, it should be
replaced with a @code{VaticanaScore} context together with some
manual @code{\layout} changes (if necessary): code like

@quotation
@verbatim
\include "gregorian.ly"

\score {
  \new VaticanaStaff { ... }
}
@end verbatim
@end quotation

@noindent
should become

@quotation
@verbatim
\new VaticanaScore {
  \new VaticanaStaff { ... }
}

\layout {
  indent = 0
  ragged-last = ##t
}
@end verbatim
@end quotation

@item
LilyPond's @q{arabic} note name language is deprecated.  While
still working for backward compatibility (if you load
@file{hel-arabic.ly}), it is recommended to use @q{english},
@q{italiano}, or your preferred note name language instead.

@item
Defaults for fret labels in fret diagrams have changed.

@itemize @minus{}
@item
The default value for @code{fret-label-vertical-offset} is set to
@w{-0.5}, which centers the label in the fret space.

@item
The default number format is now @code{'custom}, with a format
string of @code{"~dfr"} (resulting in @q{3fr}, for example),
instead of @code{'roman-lower}.
@end itemize

@item
Two new options are available for @code{fret-diagram-details}:

@itemize @minus{}
@item @code{string-overhang} allows to define the extension of string
lines beyond the last fret line, in multiples of @code{fret-distance}.
Default value@tie{}1.

@item @code{barre-thickness} defines the thickness of the barre line, in
multiples of @code{dot-radius}.  Only defined for @code{barre-type=straight}.
Default value@tie{}1.

@end itemize

@item
The command @code{\autoBeamOff} now stops auto-beaming
immediately.  Previously, its effect was delayed if a beam
generated by the auto-beamer engraver was still active.

@item
It is no longer necessary to switch off auto-beaming while using
@code{\crossStaff}.

@item
The @code{\upbow} and @code{\downbow} signs are now properly
inverted if used below a staff.  As a consequence, the glyphs
@code{scripts.upbow} and @code{scripts.downbow} have been renamed to
@code{scripts.uupbow} and @code{scripts.udownbow}, respectively, and
the new inverted glyphs are named @code{scripts.dupbow} and
@code{scripts.ddownbow}.

@lilypond[quote,verbatim]
\relative c' {
  f4^\downbow f^\upbow f_\downbow f_\upbow
}
@end lilypond

@item
In lyrics aligned to a melody, extender lines can now be added
automatically for words ending in a melisma.

@lilypond[quote,verbatim]
\relative {
  d'4 e f4 g8( f
  e4 d c2)
}
\addlyrics {
  \set autoExtenders = ##t
  A me -- lis -- ma.
}
@end lilypond

@item
By default, chord names are now always shown with English pitch
names, no longer dependent on @code{\language}.  Similarly,
commands like @code{\germanChords} are no longer dependent on
@code{\language} either.

This change might cause differences in displayed chord names.

@item
A new command @code{\englishChords} is now available, making it
possible to switch back to English chord names.

@item
Some Scheme functions related to chord names have been renamed.

@indentedblock
@multitable @columnfractions .5 .5
@headitem old @tab new
@item @code{note-name->string}
  @tab @code{pitch->name}
@item @code{alteration->text-accidental-markup}
  @tab @code{accidental->text-markup}
@item @code{note-name->markup}
  @tab @code{chord-name:markup}
@item @code{chord-name->german-markup}
  @tab @code{chord-name:german-markup}
@item @code{note-name->german-markup}
  @tab @code{chord-name:german-lowercase-name-markup}
@item @code{chord-name->italian-markup}
  @tab @code{chord-name:italian-markup}
@end multitable
@end indentedblock

@command{convert-ly} handles this automatically.

@item
Two new Scheme functions related to chord names are now available:
@code{pitch->alteration} returns the accidental for a given pitch
and language; @code{chord-name:name-markup} returns note name
markup for a given pitch and language.

@item
LilyPond now follows the Ignatzek chord name scheme more closely.
This reverts changes introduced in version 2.15.21 (in 2011),
which are now considered as incorrect and/or ambiguous.

@lilypond[quote, verbatim]
oldException = { <c e g b fis'>-\markup \super "lyd" }
chExceptions = #(append (sequential-music-to-chord-exceptions
                         oldException #t)
                        ignatzekExceptions)

music = { <c e g d'>1 | <c es g f'> | <c e g b fis'> }

\new StaffGroup \with { instrumentName = "old:" }
<<
  \new ChordNames \with {
    chordNameExceptions = #chExceptions
    additionalPitchPrefix = ""
  } \music
  \new Voice \transpose c c' \music
>>

\new StaffGroup \with { instrumentName = "new:" }
<<
  \new ChordNames \music
  \new Voice \transpose c c' \music
>>

\layout {
  indent = 1\cm
  line-width = 9\cm
  ragged-right = ##f
}
@end lilypond

@end itemize


@node Miscellaneous improvements
@unnumbered Miscellaneous improvements

@itemize

@item
The @code{\tempo} command now accepts exact rational values.  The
default formatter rounds to the nearest 0.25; the context property
@code{tempoCountPrecision} controls this.

@lilypond[quote, verbatim]
\fixed c' {
  \once \set Timing.tempoCountPrecision = #1/1000000
  \tempo 4 = #200/3
  g4 e2 f4
}
@end lilypond

@item
The new Scheme function @code{ly:parser-define-once!} defines a
variable if it is not already defined.

@item
The @code{timeSignatureFraction} context property is deprecated in
favor of @code{timeSignature}.  The new property accepts
subdivided and alternating time signatures in addition to the
simple fractions that the old property accepted.  Accessing the
old property transparently derives a simple fraction from the new
property and triggers a warning.

@item
@code{(make-music 'Music)} and @code{(make-music 'Event)} now
create music expressions that have the @code{void} property set to
@code{#t} by default.  The function @code{empty-music} has been
removed in favor of @code{(make-music 'Music)}.  The new predicate
@code{unspecified-music?}  recognizes any music expression with
the @code{void} flag set.

@item
The new Scheme function @code{ly:number->duration} converts a
duration expressed in units of whole notes to a
@code{ly:duration}.  The log, number of dots, and scaling factor
are chosen automatically.

@item
The markup commands @code{\hspace} and @code{\vspace} are used to insert space,
which may be negative.  Other objects are moved accordingly.  This movement may
be indicated by arrows printed by the new markup command @code{annotate-moving}.
Note that the arrows do not reflect the actual extents of the objects created
by @code{\vspace} and @code{\hspace}; you might use @code{\box} for that.

@lilypond[verbatim,quote]
\markup {
  left \annotate-moving \hspace #4 right
  \column { top \annotate-moving \vspace #-4/3 bottom }
}
@end lilypond

@item
The new @code{\contextPropertyCheck} command verifies that a
property is set to an expected value or is unset in a specific
context.

@item
Various context properties that previously held @code{ly:moment}
values now hold rational numbers.  To ease this transition, each
number property is paired with a fallback @code{ly:moment}
property.  Using the fallback property transparently accesses the
number property and triggers a warning.

@indentedblock
@multitable @columnfractions 0.5 0.5
@item
@b{Deprecated Context Property}
@tab
@b{New Context Property}
@c rows are sorted by deprecated property name
@item
@code{baseMoment}
@tab
@code{beatBase}
@item
@code{completionUnitAsMoment}
@tab
@code{completionUnit}
@item
@code{gridIntervalAsMoment}
@tab
@code{gridInterval}
@item
@code{measureLengthAsMoment}
@tab
@code{measureLength}
@item
@code{minimumPageTurnLength}
@tab
@code{pageTurnMinimumRestLength}
@item
@code{minimumRepeatLengthForPageTurn}
@tab
@code{pageTurnMinimumRepeatLength}
@item
@code{proportionalNotationDurationAsMoment}
@tab
@code{proportionalNotationDuration}
@item
@code{tempoWholesPerMinuteAsMoment}
@tab
@code{tempoWholesPerMinute}
@item
@code{tupletSpannerDurationAsMoment}
@tab
@code{tupletSpannerDuration}
@item
@code{voltaSpannerDurationAsMoment}
@tab
@code{voltaSpannerDuration}
@end multitable
@end indentedblock

@item
@code{\tempo @var{dur} = @var{min} - @var{max}} used to set the
context property @code{tempoWholesPerMinute} after rounding the
center of the range to the nearest integer.  It no longer rounds.
This is expected to change the MIDI tempo in certain cases.

@item
The Scheme functions @code{duration-length} and
@code{ly:duration-length} are renamed to
@code{ly:duration->number} and @code{ly:duration->moment},
respectively.

@item
The new Scheme function @code{ly:parser-append-to-include-path}
appends its argument to the current parser's include path.

@item
The value of the @code{timeSignatureSettings} context property
uses the symbol @code{beatBase} where it formerly used
@code{baseMoment}.  @command{convert-ly} does not address this
change.

@item
Embedding PNG images is now supported using the new @code{\image}
markup command.  This supplements the existing @code{\epsfile}
command for EPS images.

@code{\image} works for both PNG and EPS images.  For EPS images,
the difference between using @code{\image} and @code{\epsfile} is
that @code{\image} adds a white background by default, while
@code{\epsfile} does not.

@item
The new @code{\qr-code} markup command inserts a QR code of the
specified size for the specified URL.  This can be used to link
to, e.g., the website of a composer or publisher, the LilyPond
source files for the score, recordings, etc.

@lilypond[verbatim,quote]
\markup \qr-code #10 "https://lilypond.org"
@end lilypond

@item
Parentheses for text markup have been added to the Emmentaler
fonts, which harmonize with digits (in contrast to the already
available parentheses for accidentals).

@item
Glyphs for a figure-dash (U+2012), an en-dash (U+2013), and a
slash (U+002F) have been added to the Emmentaler fonts.

@item
A figure space (U+2007), a thin space (U+2009), and a hair space
(U+200A) have been added to the Emmentaler fonts.

@item
The @code{-dinclude-settings} option can now be given multiple times
to include several stylesheets.

@item
In the @LaTeX{} backend of @command{lilypond-book}, all inline
images are now vertically shifted.  The amount can be controlled
globally with command-line option @option{--inline-vshift} and
locally with an argument to the snippet option @code{inline}.

@item
It is possible to use various command-line options of
@command{musicxml2ly} as options for @command{lilypond-book}'s
@code{musicxmlfile} command.  This was actually introduced in
version 2.15.9 (in 2011) but stayed undocumented until now.

@item
Two new command-line options @option{-dfirst} and @option{-dlast}
have been introduced; they are equivalent to setting
@code{showFirstLength} and @code{showLastLength}, respectively, in
a LilyPond input file.  For example, saying

@example
lilypond -dlast=R1*5 ...
@end example

@noindent
makes LilyPond render only the last five measures (assuming a 4/4
time signature).

@item
A visual index of all LilyPond graphical objects (grobs) is now
available as a manual.  This is based on
@uref{https://github.com/joram-berger/visualindex,Joram Berger's
work for LilyPond 2.19}.

@item
LilyPond provides support for in-notes, i.e., footnote-like
annotations between music systems.  This isn't new (it has
actually been available since version 2.15.17, published in 2011)
but it had some flaws and wasn't documented until now.

@item
The @command{lilysong} script has been removed.  Besides lacking
any documentation, it hasn't been maintained for a long time.
Additionally, it has been using an external speech synthesis
program called @command{festival}, which is no longer maintained
either.

@item
Two new spacing styles are available for the @code{space-alist}
grob property: @code{shrink-space} and @code{semi-shrink-space};
these spaces only shrink and don't stretch.  They are also used
directly in LilyPond, improving the formatting of tightly spaced
staves.

@item
The @command{lilypond} binary has a new command-line option
@option{-dstaff-size} to set the global staff size, equivalent to
setting @code{set-global-staff-size} in a LilyPond input file.

@item
Instead of the functions @code{\bookOutputName} and
@code{\bookOutputSuffix} we now recommend using the paper
variables @code{output-filename} and @code{output-suffix} (which
are not new but stayed undocumented until now).  While the former
will work unchanged, the latter is more coherent and easier to
understand, especially if combined with predefined paper
variables.

@item
The @code{Stem.details.lengths} property now also accepts pairs as
list elements, allowing to set the length for up and down stems
separately.

@item
The @code{ly:self-alignment-interface::aligned-on-x-parent}
function (used by many grobs to compute the x-offset) now listens
to a new @code{PaperColumn} property called
@code{X-alignment-extent}.  Set by default, it provides a fallback
width for the @code{PaperColumn} grob in case it doesn't contain
note heads.  This helps align dynamic scripts that are attached to
spacer rests, for example.

@lilypond[quote,verbatim]
music =
  \new Staff <<
    { f'2 g'2 }
    { s4\f s\f s\f s\f }
  >>

\score {
  \music
}

\score {
  \music

  \layout {
    \context {
      \Score
      \override PaperColumn.X-alignment-extent = ##f
    }
  }
}
@end lilypond

@item
@code{BassFigureContinuation} grobs now support
@code{horizontal-line-spanner-interface}; the @code{padding}
property has been replaced with the corresponding subproperties in
@code{bound-details}.

@item
The @code{\align-on-other} markup command now accepts @code{#f} as
a value for the alignment, indicating a markup's reference point.

@item
A new function @code{\withRelativeDir} is now available for markup
commands that include files, and where such files should be found
relative to the input file.  Example:

@example
\markup @{ \image #X #3 \withRelativeDir "test.png" @}
@end example

@item
The positioning of horizontal (analysis) brackets has been
improved; in particular, the @code{HorizontalBracket} grob now has
an @code{outside-staff-priority} value of 800.  As a consequence,
however, nested horizontal brackets might be positioned
differently than before.  You can fix this by adjusting
@code{outside-staff-priority} values with @code{\tweak} (where the
outermost bracket should get the highest priority value).

@item
A new Scheme function @code{to-staff-space} is provided to convert
absolute dimensions (in various units) to staff-space units.
Examples:

@example
top-markup-spacing.basic-distance = #(to-staff-space 2 'cm)

% default unit is pt
\markup
  \override #`(baseline-skip . ,(to-staff-space 20))
  \column @{
    foo
    bar
  @}
@end example

@item
Two new markup functions @code{\abs-hspace} and @code{\abs-vspace}
are available to provide absolute dimensions that stay the same
regardless of the current staff size.

@item
The data emitted by the command-line option
@option{-dshow-available-fonts} is now sent to standard output.

@item
The function @code{ly:font-config-display-fonts} now takes an
optional argument for output port selection.

@item
Scheme command-line option handling is now more robust.  In the
course of the new implementation, some minor changes were
necessary.

@itemize @minus{}
@item
On the command line, the argument for the @option{-dpaper-size}
option no longer needs to be extra-quoted, i.e., a call like
@code{-dpaper-size=a3} works just fine.

@item
The @option{pixmap-format} option now expects a string as a value,
not a symbol.  No change on the command line, but a call like

@example
#(ly:set-option 'pixmap-format 'pngalpha)
@end example

@noindent
must be changed to

@example
#(ly:set-option 'pixmap-format "pngalpha")
@end example

The same holds for options @option{separate-page-formats} and
@option{tall-page-formats}.  Note that @command{convert-ly} can
handle this automatically.
@end itemize

@item
The @code{side-position-interface} now offers two new properties,
@code{X-padding} and @code{minimum-X-space}, to control the
horizontal padding and minimum distance to a grob's parent object,
independently of the vertical padding and minimum distance.  This
is useful for grobs like @code{Fingering} that can be attached
either horizontally or vertically to note heads, and which need
different padding values for the X- and Y-axis, respectively.

@item
@code{\pushContextProperty} and @code{\popContextProperty} are two
new commands for manipulating context properties.  The first one
pushes the current value to a stack, while the second one pops off
the value from the stack and uses it to restore the property.

@lilypond[quote,verbatim]
{
  c'
  \pushContextProperty Staff.fontSize
  \set Staff.fontSize = 3
  c'
  \pushContextProperty Staff.fontSize
  \set Staff.fontSize = 6
  c'
  \popContextProperty Staff.fontSize
  c'
  \popContextProperty Staff.fontSize
  c'
}
@end lilypond

@item
A new grob property @code{whiteout-color} is available to set the
color used for white-out operations.  Similarly, the
@code{\whiteout} markup command now listens to a @code{color}
property to do the same.

@item
The @command{musicxml2ly} script has been completely revised to
better convert MusicXML to LilyPond.  It now supports more
MusicXML features and elements and tries to be more faithful in
the conversion, retaining more of the original appearance if
possible (and sensible).

Here is a list of some notable changes (not taking bug fixes into
account).

@itemize @minus{}
@item The script is now much faster.

@item Overlapping and nested slurs work as expected.

@item Better automatic support of circumventing LilyPond's
infamous issue #34 (i.e., synchronization of grace note timing
between staves at the beginning of a piece).

@item Support of two-stem tremolos and nested tuplets.

@item Color and font size support for almost all MusicXML
elements.  A new command-line option @option{--dynamics-scale}
helps compensate glyph size differences of dynamics signs in
various music fonts.

@item Correct handling of ottava endings for MusicXML files
created by Finale.  The script looks at the @code{<software>}
element to detect the used notation software.  If necessary, this
can be overridden with the new command-line option
@option{--ottavas-end-early}.

@item Option @option{--shift-meter} has been replaced with option
@option{--shift-durations}, using a simpler syntax.

@item New command-line option @option{--no-tagline} to suppress
the output of a LilyPond tagline.

@item New command-line option @option{--book} to wrap the
top-level score with @code{\book}.

@item If @code{<credit>} elements are present, they now fill the
fields in LilyPond's @code{\header} block instead of metadata
elements like @code{<work-title>} or @code{<creator>}.

@item New command-line option @option{--credit-page} to specify
the page from which LilyPond should take @code{<credit>} data to
fill the @code{\header} block.

@item All metadata elements that are not mapped to standard
@code{\header} fields (and which are not ignored like the @q{page
number} type) are output with more consistent field names: the
prefix @samp{id:@tie{}} is used for @code{<identification>}
children, @samp{credit:@tie{}} for @code{<credit>} elements, and
the MusicXML element name (without a prefix) in all other cases.
As a consequence, some (unused) fields got new names.

@indentedblock
@multitable @columnfractions 0.3 0.4
@headitem old                    @tab new
@item @code{movementnumber}      @tab @code{movement-number}
@item @code{encodingsoftware}    @tab @code{id: software}
@item @code{encodingdate}        @tab @code{id: encoding-date}
@item @code{encoder}             @tab @code{id: encoder}
@item @code{encodingdescription} @tab @code{id: encoding-description}
@item @code{source}              @tab @code{id: source}
@end multitable
@end indentedblock

@item The bar numbers shown as comments in the created LilyPond
input file are now as expected, i.e., the values shown refer to
the previous bar.

@end itemize

@item
The markup command @code{\page-ref} has a new property
@code{x-align} to control the X-alignment of the
gauge replacement.

@lilypond[quote,verbatim]
\markup {
  \box
    \page-ref #'foo "???" "?" " right-aligned (default)"
}
\markup {
  \box
    \override #`(x-align . ,LEFT)
    \page-ref #'foo "???" "?" " left-aligned"
}
\markup {
  \box
    \override #'(x-align . -2.5)
    \page-ref #'foo "???" "?" " left outside"
}
@end lilypond

@item
It is now also possible to set the @code{ledger-extra} property via the
@code{NoteHead} grob.

@lilypond[quote,verbatim]
\score {
  {
    c'''1
    \tweak ledger-extra #4 c'''1
    c'''1
  }
}
@end lilypond

@item
For grob @code{NonMusicalPaperColumn}, the subproperty
@code{bottom-space} of the @code{line-break-system-details}
property has been renamed to @code{bottom-padding}.  While
available since version 2.13.4 (released in 2009) it wasn't
documented before.

@item
It is now possible to modify tag groups created with
@code{\tagGroup} or @code{\tagGroupRef} by using the
commands @code{\resetTagGroups}, @code{\resetTagGroup},
@code{\addToTagGroup}, and @code{\removeFromTagGroup}.

@item
The current input language (as selected with @code{\language}) can
be accessed in the new Scheme variable @code{input-language} (as a
symbol).

@item
The new function @code{\breakAlignInsert} makes it easy to
change the order of notational elements like clefs, time
signatures, bar lines etc.  Previously, this required
re-defining the @code{Score.BreakAlignment.break-align-orders}
vector.

@lilypond[quote,verbatim]
{
  g'1
  \key f \major
  g'
  \breakAlignInsert staff-bar after key-signature
  \key g \minor
  g'
}
@end lilypond

@item
The output option @option{-dcrop} now takes all stencils
into account while calculating the bounding box.
This can change the size of cropped output.

@item
These functions, which have been deprecated since version 2.13.19,
have been removed: @code{\deprecatedcresc},
@code{\deprecatedendcresc}, @code{\deprecateddim}, and
@code{\deprecatedenddim}.

@end itemize


@ifhtml
For older news, go to
@uref{https://lilypond.org/doc/v2.22/Documentation/changes/},
or @uref{../,go back} to the Documentation index.

@end ifhtml

@bye
