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