Documentation/changes.tely

   1 \input texinfo @c -*- coding: utf-8; mode: texinfo; -*-
   2 @setfilename lilypond-changes.info
   3 @settitle LilyPond Changes
   4
   5 @include macros.itexi
   6
   7 @ifhtml
   8 @macro inputfileref{DIR,NAME}
   9 @uref{../../\DIR\/collated-files.html#\NAME\,@file{\DIR\/\NAME\}}@c
  10 @end macro
  11 @macro usermanref{NAME}
  12 @inforef{\NAME\,,../user/lilypond/lilypond}@c
  13 @end macro
  14 @end ifhtml
  15
  16 @ifnothtml
  17 @macro inputfileref{DIR,NAME}
  18 @file{\DIR\/\NAME\}@c
  19 @end macro
  20 @macro usermanref{NAME}
  21 See user manual, \NAME\
  22 @end macro
  23 @end ifnothtml
  24
  25 @macro textanchor{NAME}
  26 @html
  27 <a name="\NAME\"></a>
  28 @end html
  29 @end macro
  30
  31
  32 @documentencoding utf-8
  33 @documentlanguage en
  34 @afourpaper
  35
  36 @finalout
  37
  38 @node Top
  39 @top New features in 2.18 since 2.16
  40
  41 @allowcodebreaks false
  42
  43 @itemize
  44
  45 @ignore
  46
  47 HINTS
  48
  49 * add new items at the top
  50
  51 * only show verbatim input for syntax/input changes
  52
  53 * try to be as brief possible in those cases
  54
  55 * don't try to provide real-world examples, they often get too big,
  56 which scares away people.
  57
  58 * Write complete sentences.
  59
  60 * only show user-visible changes.
  61
  62 @end ignore
  63
  64 @item
  65 A number of shorthands like @code{(}, @code{)}, @code{|},
  66 @code{[}, @code{]}, @code{~}, @code{\(}, @code{\)} and others can
  67 now freely be redefined like normal commands.  An example would be
  68 @lilypond[verbatim,quote]
  69 "\\{" = (
  70 "\\}" = )
  71 "(" = \melisma
  72 ")" = \melismaEnd
  73
  74 \new Staff <<
  75   \relative c' {
  76     c8 \{ d e f \} % slurred
  77     g ( a b c ) % no slur, but with melisma
  78     c,1 \bar "|."
  79    }
  80    \addlyrics { Li -- ly -- pond. }
  81 >>
  82 @end lilypond
  83
  84 @item
  85 The articulation shorthand for @code{\staccatissimo} has been
  86 renamed from @code{-|} to@tie{}@code{-!}.
  87
  88 @item
  89 Tempo change ranges are now written as @code{\tempo 4 = 60 - 68}
  90 rather than @code{\tempo 4 = 60 ~ 68}.
  91
  92 @item
  93 Grob @code{OctavateEight} was renamed to @code{ClefModifier}.
  94 Related context properties were renamed from @code{xxxOctavationyyy}
  95 to @code{xxxTranspositionyyy}.
  96
  97 @item
  98 There is a new @code{\absolute} command explicitly marking music
  99 as being entered in absolute pitch.  While this has been the
 100 default previously, an explicit @code{\absolute} also prevents
 101 reinterpretation when the passage is placed inside of
 102 @code{\relative}:
 103 @lilypond[verbatim,quote]
 104 \relative c { c'4 \absolute { f'' g'' } c }
 105 @end lilypond
 106
 107 @item
 108 When @code{\relative} is used without an explicit reference pitch,
 109 the reference pitch now is the middle of the first octave, making
 110 the first entered pitch indistinguishable from absolute pitch.
 111 Previously, omitting the reference pitch would have lead to a
 112 default of @code{c'}.  Since that choice was somewhat arbitrary,
 113 recommended usage was to always specify the reference pitch.
 114
 115 @item
 116 A new command @code{\single} can be used for converting a property
 117 override into a tweak to be applied on a single music expression:
 118
 119 @lilypond[quote,verbatim,relative=2]
 120 <a \single\voiceTwoStyle e' a>1
 121 @end lilypond
 122
 123 @item
 124 Two ways of letting graphical objects not appear in the output are
 125 overriding its @code{transparent} property with @code{#t}
 126 (retaining the original spacing) or overriding its @code{stencil}
 127 property with @code{#f} (not using any space at all).  Those two
 128 operations now have the shorthands @code{\hide} and @code{\omit},
 129 respectively.  They can either be given a music expression to
 130 tweak, or the name of a graphical object for which an override
 131 should be created (for specifying both, use @code{\single} on the
 132 override form):
 133
 134 @lilypond[quote,verbatim]
 135 \new Staff \with { \omit Clef }
 136 \relative c'' <a e' \hide a>1
 137 @end lilypond
 138
 139 @item
 140 A new command @code{\temporary} can be applied to overrides in
 141 order to not have them replace previous property settings.  If a
 142 @code{\revert} is applied to the same property subsequently, the
 143 previous setting reappears:
 144
 145 @lilypond[quote,verbatim,relative=2]
 146 \override NoteHead.color = #red c4
 147 \override NoteHead.color = #green d
 148 \revert NoteHead.color e2
 149 \override NoteHead.color = #red c4
 150 \temporary\override NoteHead.color = #green d
 151 \revert NoteHead.color e
 152 \revert NoteHead.color c
 153 @end lilypond
 154
 155 This is mainly useful for writing music functions that need to
 156 have some property changed just for the duration of the function.
 157
 158 @item
 159 @code{\tag}, @code{\removeWithTag}, and @code{\keepWithTag} can
 160 now accept a list of symbols rather than just a single symbol for
 161 marking, removing, and keeping music with any of multiple tags.
 162 This is particularly important for @code{\keepWithTag} since one
 163 cannot achieve the same effect by using multiple consecutive
 164 @code{\keepWithTag} commands.
 165
 166 @item
 167 The @samp{-d old-relative} option has been removed.  Not actually
 168 accessible from the command line any more, its remaining use was
 169 for interpretating @code{\relative} in LilyPond files converted
 170 automatically from version@tie{}1.8 or older.  It is unclear how
 171 much of this was actually still operative.
 172
 173 @item
 174 The meaning of @code{instrumentTransposition} has been reversed.
 175 After
 176 @example
 177 \set instrumentTransposition = #@{ b #@}
 178 @end example
 179 a written @code{c'} now sounds like @code{b}.  Previously, this
 180 would have been the other way round.  This and the following change
 181 should make dealing with transposing instruments more
 182 straightforward.
 183
 184 @item
 185 The music generated by @code{\set} and @code{\override} commands
 186 is no longer affected by @code{\transpose}.  The main consequence
 187 is that @code{\transpose} will transpose audible/@/concert pitch and
 188 printed pitch by the same amount even when the transposed music
 189 contains @code{\transposition}.  Previously,
 190 @example
 191 \transpose c' f' \transposition bes'
 192 @end example
 193 was equivalent to @code{\transposition f'}.  Now it stays
 194 equivalent to @code{\transposition bes'}.
 195
 196 @item
 197 When checking for collisions, LilyPond no longer treats objects as
 198 rectangles.  Instead, the actual shape of objects is approximated
 199 using an integral-like approach.  This generally results in more
 200 even and snug positioning of objects and systems:
 201
 202 @lilypond[relative=1]
 203 #(ly:set-option 'debug-skylines #t)
 204 \dynamicUp
 205 c'4\f a4\f d\f( f)
 206 a,4\< c c c\!
 207 d4-.\downbow a4^"r'venu..." c \tempo "T1" e
 208 @end lilypond
 209
 210 Previously, the above snippet looked like this:
 211
 212 @lilypond[relative=1]
 213 #(ly:set-option 'debug-skylines #t)
 214 \override Hairpin #'vertical-skylines = #'()
 215 \override DynamicText #'vertical-skylines = #'()
 216 \override TextScript #'vertical-skylines = #'()
 217 \override Score.MetronomeMark #'vertical-skylines = #'()
 218 \override Staff.Clef #'vertical-skylines = #'()
 219 \dynamicUp
 220 c'4\f a4\f d\f( f)
 221 a,4\< c c c\!
 222 d4-.\downbow a4^"r'venu..." c \tempo "T1" e
 223 @end lilypond
 224
 225 Affected objects include @code{Accidentals}, @code{Beams}, @code{Clefs},
 226 @code{Dynamics}, @code{FiguredBass}, @code{Flags}, @code{Glissandos},
 227 @code{Lyrics}, @code{MetronomeMarks}, @code{OttavaBrackets},
 228 @code{Pedals}, @code{RehearsalMarks}, @code{Rests}, @code{Scripts},
 229 @code{TextScripts}, @code{Ties}, @code{Tuplets} and @code{VoltaBrackets}.
 230
 231 @item
 232 Tuplets are now created with the @code{\tuplet} command, which
 233 takes a fraction @code{@var{t}/@var{n}} to specify that @var{t}
 234 notes are played in the time usually allowed for @var{n}. One
 235 @code{\tuplet} command can create several tuplet groups if their
 236 duration is typed after the fraction.
 237 @lilypond[quote,verbatim,relative=2]
 238 \tuplet 3/2 { c8 d e } \tuplet 3/2 { f e d } c2
 239 \tuplet 3/2 4 { c8 d e f e d } c2
 240 @end lilypond
 241 The @code{\times} command with its inverted fraction order
 242 @code{@var{n}/@var{t}} is still available.
 243
 244 @item
 245 Introducing two new markup-commands; @code{\draw-dashed-line} and
 246 @code{\draw-dotted-line}.
 247
 248 @noindent
 249 The dashed-line extends to the whole length given by @var{dest}, if
 250 @code{full-length} is set to @code{#t} (this is the default) without any
 251 space at the beginning or end.  @code{off} will then be altered to fit.
 252 To insist on the given (or default) values of @code{on}, @code{off} use
 253 @code{\override #'(full-length . #f)}.  Manual settings for @code{on},
 254 @code{off} and @code{phase} are possible.
 255
 256 @noindent
 257 The dotted-line always extends to the whole length given by @var{dest},
 258 without any space at the beginning or end.  Manual settings for
 259 @code{off} are possible to get larger or smaller space between the dots.
 260 The given (or default) value of @code{off} will be altered to fit the
 261 line-length.
 262
 263 @lilypond[verbatim,quote]
 264 \markup {
 265   \draw-dashed-line #'(5.1 . 2.3)
 266   \override #'(on . 0.3)
 267   \override #'(off . 0.5)
 268   \draw-dashed-line #'(5.1 . 2.3)
 269   \draw-dotted-line #'(5.1 . 2.3)
 270   \override #'(thickness . 2)
 271   \override #'(off . 0.2)
 272   \draw-dotted-line #'(5.1 . 2.3)
 273 }
 274 @end lilypond
 275
 276 @item
 277 Starting with version@tie{}2.17.10, error messages or the
 278 @code{textedit} @acronym{URI} used for point-and-click
 279 functionality specify column numbers starting with@tie{}1 rather
 280 than@tie{}0.  The byte offset (also part of @code{textedit}
 281 @acronym{URI}s) still starts at@tie{}0.
 282
 283 @item
 284 The @code{\clef} command supports optional transposition:
 285 @lilypond[verbatim,quote,relative=1]
 286 \clef "treble_(8)"
 287 c2 c
 288 \clef "bass^[15]"
 289 c2 c
 290 @end lilypond
 291
 292 @item
 293 The LilyPond syntax of dot-separated words @code{Voice.Accidental}
 294 has been made interchangeable with @code{#'(Voice Accidental)}, a
 295 Scheme list of symbols.  As one result, code like
 296 @example
 297 \override Voice.TextSpanner #'(bound-details left text) = "rit."
 298 @end example
 299 is now equivalent to
 300 @example
 301 \override Voice.TextSpanner bound-details.left.text = "rit."
 302 @end example
 303 or even
 304 @example
 305 \override #'(Voice TextSpanner) bound-details.left.text = "rit."
 306 @end example
 307
 308 @item
 309 Grob and grob property path no longer need to be specified as two
 310 separate arguments to commands like @samp{\override} and
 311 @code{\revert}, allowing for the syntax
 312 @example
 313 \override Voice.TextSpanner.bound-details.left.text = "rit."
 314 @end example
 315 Since complementary music functions like @samp{\overrideProperty}
 316 cannot support forms with and without separating space at the same
 317 time, using a single dotted path is now the preferred form.
 318 Specifying grob path and grob property path separately, currently
 319 still supported with @samp{\override} and @samp{\revert} for
 320 compatibility reasons, is deprecated.
 321
 322 @item
 323 Due to words now being accepted as symbol function arguments, the
 324 interfaces of @samp{\accidentalStyle}, @samp{\alterBroken},
 325 @samp{\footnote} and @samp{\tweak} had to be redesigned where
 326 optional symbol arguments were involved.  Please check the
 327 respective music function documentation for details.
 328
 329 @item
 330 Several commands now accept symbol lists (conveniently entered as
 331 dot-separated words) for various kinds of arguments.  These
 332 include @samp{\accidentalStyle}, @samp{\alterBroken},
 333 @samp{\footnote}, @samp{\hide}, @samp{\omit},
 334 @samp{\overrideProperty}, @samp{\shape}, and @samp{\tweak}.
 335
 336 @item
 337 The bar line user interface has changed. Bar glyphs now resemble the
 338 appearance of the bar line, so a left repeat sign has to be coded
 339 as @code{.|:}. The command @code{\defineBarLine} provides an easy way
 340 to define additional bar line styles.
 341
 342 @item
 343 Accidentals in the key signature may be printed in octaves other
 344 than their traditional positions, or in multiple octaves.
 345 @lilypond[quote,relative=0]
 346 \override Staff.KeySignature #'flat-positions = #'((-5 . 5))
 347 \override Staff.KeyCancellation #'flat-positions = #'((-5 . 5))
 348 \clef bass \key es \major es g bes d
 349 \clef treble \bar "||" \key es \major es g bes d
 350 \override Staff.KeySignature #'sharp-positions = #'(2)
 351 \bar "||" \key d \major b fis b2
 352 @end lilypond
 353
 354 @end itemize
 355
 356 @ifhtml
 357 For older news, go to
 358 @uref{http://lilypond.org/doc/v2.16/Documentation/changes/},
 359 @uref{http://lilypond.org/doc/v2.14/Documentation/changes/},
 360 or @uref{../,go back} to the Documentation index.
 361
 362
 363 @end ifhtml
 364
 365 @bye