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