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