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