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