LilyPond — Changes
******************

This document lists changes and new features in LilyPond version 2.25.6
since 2.24.

          Note: 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 *strongly recommended* to use the ‘convert-ly’
          tool distributed with LilyPond, which is described in *note
          (lilypond-usage)Updating files with convert-ly::.
          ‘convert-ly’ can perform almost all syntax updates
          automatically.  Frescobaldi users can run ‘convert-ly’
          directly from Frescobaldi using “Tools > Update with
          convert-ly...”.  Other editing environments with LilyPond
          support may provide a way to run ‘convert-ly’ graphically.

Major changes in LilyPond
*************************

   • 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 2.25.6),
     add the following code:

          \paper {
            top-margin = 5\mm
            bottom-margin = 10\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
          }

   • 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 ‘Cairo backend’, and can be turned on using the
     ‘-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 ‘-dembed-source-code’ option for PDF, and the
     ‘output-attributes’ property for SVG.

New for musical notation
************************

Pitches improvements
====================

   • Certain spurious change clefs have been fixed.

          {
            R1
            \clef treble
            R1
          }
[[image of music]]

Rhythm improvements
===================

   • Bar checks (‘|’) 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.

   • The new option ‘span-all-note-heads’ may be used to make tuplet
     brackets span all note heads (not just the stems) as recommended by
     Gould and Ross.

[[image of music]]

Expressive mark improvements
============================

   • Two new variant glyphs for breathing signs are available:
     ‘laltcomma’ and ‘raltcomma’.  These glyphs represent the old shapes
     of ‘lcomma’ and ‘rcomma’, respectively, before changing them to
     more common shapes.

          {
            \override BreathingSign.text =
              \markup { \musicglyph "scripts.raltcomma" }
            f'2 \breathe f' |
          }
[[image of music]]

Repeat improvements
===================

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

   • Using the new ‘printInitialRepeatBar’ property, it is possible to
     make a start repeat bar line automatically printed even at the
     beginning of the piece.

[[image of music]]

   • The volta number position relative to the the volta bracket can now
     be adjusted with the ‘volta-number-offset’ property of
     ‘VoltaBracket’.

Editorial annotation improvements
=================================

   • ‘NoteName’ grobs are now horizontally centered by default.

Text and font improvements
==========================

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

          \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"))
          }

     or

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

     the new syntax is

          \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"
          }

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

     There is no ‘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):

          \layout {
            \context {
              \Score
              \override SystemStartBrace.fonts.music = "lilyjazz"
            }
          }
          
          \new PianoStaff <<
            \new Staff { c' }
            \new Staff { c' }
          >>
          
          \markup \override #'(fonts . ((music . "lilyjazz"))) \left-brace #20

     Because ‘fonts’ is simply a property, it is possible to override it
     on a per-grob basis, e.g.,

          \layout {
            \override Score.SectionLabel.fonts.roman = "Custom font"
          }

     This is preferable over the already existing ‘font-name’ property,
     since the latter makes commands such as ‘\bold’ ineffective,
     instead requiring to include “Bold” in the ‘font-name’ string.
     Using ‘fonts’ does not have such effects.

   • The ‘\lookup’ markup command can now only be used for braces; for
     other glyphs, use the ‘\musicglyph’ command.  Instead of ‘\lookup’,
     it is also generally recommended to use ‘\left-brace’.

   • 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 ‘\serif’, ‘\sans’ or ‘\typewriter’ markup
     commands.  For example:

          dolceP =
          #(make-dynamic-script
            #{
              \markup {
                \serif \normal-weight dolce
                p
              }
            #})

          { c'\dolceP }
[[image of music]]

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

   • The ‘font-series’ property is now more flexible and allows to
     specify values such as ‘semibold’ and ‘light’ instead of only
     ‘normal’ and ‘bold’.

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

   • The new ‘font-stretch’ property allows selecting a condensed or
     expanded font.

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

          \set Score.repeatCommands = #'((volta "2, 5"))

     to

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

   • In markup, fingerings (‘\markup \finger’) and bass figures
     (‘\markup \figured-bass’) now get scaled along with normal text
     when using ‘\fontsize’.

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

          \myText
          \markup\fontsize #6 \myText
[[image of music]]

     The previous behavior can be restored by setting the global
     variables ‘legacy-figured-bass-markup-fontsize’ and
     ‘legacy-finger-markup-fontsize’ to true, respectively:

          #(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
[[image of music]]

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

   • The ‘\text’ markup command has been removed.  Instead, the
     ‘\serif’, ‘\sans’ or ‘\typewriter’ markup commands should be used.
     These commands used to set the font style _only if a normal text
     font was used_ (not a musical font, such as for dynamics), but now
     they _both_ set the font style and make a normal text font used.

New for specialist notation
***************************

   • For orthogonality with other ancient clefs, five new mensural clefs
     are available: ‘"mensural-f2"’, ‘"mensural-f3"’, ‘"mensural-f4"’
     (same as ‘"mensural-f"’), ‘"mensural-f5"’, ‘"mensural-g1"’,
     ‘"mensural-g2"’ (same as ‘"mensural-g"’).

   • The default time signature and accidental style in a
     ‘PetrucciStaff’ context is now the same as in ‘MensuralStaff’.

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

          \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 \]
              \[ \once \override NoteHead.left-down-stem = ##t
                 a\breve b
                 \once \override NoteHead.right-down-stem = ##t
                 g\longa \]
              \[ \once \override NoteHead.right-down-stem = ##t
                 b\maxima
                 \once \override NoteHead.right-up-stem = ##t
                 g\longa \]
            }
            \layout {
              \context {
                \Voice
                \remove Ligature_bracket_engraver
                \consists Mensural_ligature_engraver
              }
            }
          }
[[image of music]]

   • The use of the ‘gregorian.ly’ is deprecated.  While still working
     for backward compatibility, it should be replaced with a
     ‘VaticanaScore’ context together with some manual ‘\layout’ changes
     (if necessary): code like

          \include "gregorian.ly"
          
          \score {
            \new VaticanaStaff { ... }
          }

     should become

          \new VaticanaScore {
            \new VaticanaStaff { ... }
          }
          
          \layout {
            indent = 0
            ragged-last = ##t
          }

Miscellaneous improvements
**************************

   • Embedding PNG images is now supported using the new ‘\image’ markup
     command.  This supplements the existing ‘\epsfile’ command for EPS
     images.

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

   • The new ‘\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.

          \markup \qr-code #10 "https://lilypond.org"
[[image of music]]

   • A figure-dash glyph (U+2012) and an en-dash glyph (U+2013) have
     been added to the Emmentaler fonts.

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

   • The ‘-dinclude-settings’ option can now be given multiple times to
     include several stylesheets.

