Add Changes entry for -dstrokeadjust and "Usage" entry.

[lilypond.git] / Documentation / changes.tely

\input texinfo @c -*- coding: utf-8; mode: texinfo; -*-
@setfilename lilypond-changes.info
@settitle LilyPond Changes

@include macros.itexi

@ifhtml
@macro inputfileref{DIR,NAME}
@uref{../../\DIR\/collated-files.html#\NAME\,@file{\DIR\/\NAME\}}@c
@end macro
@macro usermanref{NAME}
@inforef{\NAME\,,../user/lilypond/lilypond}@c
@end macro
@end ifhtml

@ifnothtml
@macro inputfileref{DIR,NAME}
@file{\DIR\/\NAME\}@c
@end macro
@macro usermanref{NAME}
See user manual, \NAME\
@end macro
@end ifnothtml

@macro textanchor{NAME}
@html
<a name="\NAME\"></a>
@end html
@end macro


@documentencoding utf-8
@documentlanguage en
@afourpaper

@finalout

@node Top
@top New features in 2.18 since 2.16

@allowcodebreaks false

@itemize

@ignore

HINTS

* add new items at the top

* only show verbatim input for syntax/input changes

* try to be as brief possible in those cases

* don't try to provide real-world examples, they often get too big,
which scares away people.

* Write complete sentences.

* only show user-visible changes.

@end ignore

@item
The PostScript functionality of stroke adjustment is no longer
applied automatically but left to the discretion of the PostScript
device (by default, Ghostscript uses it for resolutions up to
150dpi when generating raster images).  When it is enabled, a more
complex drawing algorithm designed to benefit from stroke
adjustment is employed mostly for stems and bar lines.

Stroke adjustment can be forced by specifying the command line
option @samp{-dstrokeadjust} to LilyPond.  When generating
@code{PDF} files, this will usually result in markedly better
looking @code{PDF} previews but significantly larger file size.
Print quality at high resolutions will be unaffected.

@item
There is now a new context type called @code{NullVoice} which, while not
appearing in the printed output, can be used to align lyrics.  This can
be particularly convenient when used in parallel with a
@code{\partcombine} construct.

@lilypond[verbatim,quote]
soprano = \relative c' { c e g c }
alto = \relative c' { a c e g }
verse = \lyricmode { This is my song }

\score {
  \new Staff <<
    \partcombine \soprano \alto
    \new NullVoice = "aligner" \soprano
    \new Lyrics \lyricsto "aligner" \verse
  >>
  \layout {}
}
@end lilypond


@item
Several articulations can be put into a single variable or
returned from an event function:

@lilypond[verbatim,quote]
sempreStacc = -. ^\markup \italic sempre
\relative { c''4\sempreStacc c c c }
@end lilypond

@item
The baseline of score markups is now taken from the reference
point (usually the middle of the staff) of the first bottom system
rather than the top of the bounding rectangle.  The following
@lilypond[verbatim,quote]
\markup {
  violin: \score { \new Staff { <g d' a' e''>1 }
                   \layout { indent=0 } } ,
  cello: \score { \new Staff { \clef "bass" <c, g, d a> }
                  \layout { indent=0 } }
}
@end lilypond
previously looked like
@lilypond[quote]
\markup {
  violin: \general-align #Y #UP
          \score { \new Staff { <g d' a' e''>1 }
                   \layout { indent=0 } } ,
  cello:  \general-align #Y #UP
          \score { \new Staff { \clef "bass" <c, g, d a> }
                  \layout { indent=0 } }
}
@end lilypond
without a reliable way to get both scores to line up.

@item
LilyPond no longer automatically infers a @samp{\defaultchild}
context in a context definition with @samp{\accepts} clauses.  Any
context definition without an explicit or inherited
@samp{\defaultchild} definition counts as a @samp{Bottom} context
and will be eligible for rhythmic events and overrides without
causing the implicit creation of other contexts.  Be sure to
specify a @samp{\defaultchild} for non-@samp{Bottom} contexts when
defining them from scratch.

@item
There is now extensive support for both discant and bass accordion
register symbols in the @samp{scm accreg} module, see
@ruser{Accordion Registers}.
@lilypond[verbatim,quote]
#(use-modules (scm accreg))
\new PianoStaff
<<
  \new Staff \relative
  { \clef "treble"  \discant "10"
    r8 s32 f'[ bes f] s e[ a e] s d[ g d] s16 e32[ a]
    \discant "121"
    << { r16 <f bes> r <e a> r <d g> } \\
       { d r a r bes r } >> |
    <cis e a>1
  }
  \new Staff \relative
  { \clef "treble"  \freeBass "1"
    r8 d'32 s16. c32 s16. bes32 s16. a32[ cis] s16
    \clef "bass"  \stdBass "Master"
    << { r16 <f, bes d>^"b" r <e a c>^"am" r <d g bes>^"gm" |
         <e a cis>1^"a" } \\
       { d8_"D" c_"C" bes_"B" | a1_"A" }
    >>
  }
>>
@end lilypond

@item
New commands @code{markLengthOn} and @code{markLengthOff} control
the allowance of horizontal space for tempo and rehearsal marks.

@lilypond[quote,relative=2]
\markLengthOn
\compressFullBarRests
\tempo "Molto vivace" c2 c'
\mark\default
\tempo "Meno mosso" R1*16
\mark\default
g,2 g
\bar "||"
\markLengthOff
\tempo "Molto vivace" c2 c'
\mark#1
\tempo "Meno mosso" R1*16
\mark\default
g,2 g
@end lilypond

@item
Rehearsal marks at the beginning of a line are now placed to the right
of the clef and key signature by default.  As in previous versions, the
@code{break-alignable-interface} controls the behavior.

@lilypond[quote,relative=2]
\set Score.barNumberVisibility = #all-bar-numbers-visible
\set Timing.currentBarNumber = #72
\bar"||" \time 3/4 \key e\major \mark#10 \tempo "Adagio" b2.
@end lilypond

@item
Decimal numbers can now be written directly in music,
without a hash sign.  Together with the previous change
in the way object properties are specified, the code to
change the length of stems has changed from this:
@example
\override Stem #'length = #5.6
e' f' g' a'
@end example
to this:
@example
\override Stem.length = 5.6
e' f' g' a'
@end example

One has to write a digit on both sides of the dot -- values like
@code{4.} or @code{-.3} are not allowed.

Decimal fractions are also not accepted in @code{\chordmode}.

@item
A number of shorthands like @code{(}, @code{)}, @code{|},
@code{[}, @code{]}, @code{~}, @code{\(}, @code{\)} and others can
now freely be redefined like normal commands.  An example would be
@lilypond[verbatim,quote]
"\\{" = (
"\\}" = )
"(" = \melisma
")" = \melismaEnd

\new Staff <<
  \relative c' {
    c8 \{ d e f \} % slurred
    g ( a b c ) % no slur, but with melisma
    c,1 \bar "|."
   }
   \addlyrics { Li -- ly -- pond. }
>>
@end lilypond

@item
The articulation shorthand for @code{\staccatissimo} has been
renamed from @code{-|} to@tie{}@code{-!}.

@item
Tempo change ranges are now written as @code{\tempo 4 = 60 - 68}
rather than @code{\tempo 4 = 60 ~ 68}.

@item
Grob @code{OctavateEight} was renamed to @code{ClefModifier}.
Related context properties were renamed from @code{xxxOctavationyyy}
to @code{xxxTranspositionyyy}.

@item
There is a new @code{\absolute} command explicitly marking music
as being entered in absolute pitch.  While this has been the
default previously, an explicit @code{\absolute} also prevents
reinterpretation when the passage is placed inside of
@code{\relative}:
@lilypond[verbatim,quote]
\relative c { c'4 \absolute { f'' g'' } c }
@end lilypond

@item
When @code{\relative} is used without an explicit reference pitch,
the reference pitch now is the middle of the first octave, making
the first entered pitch indistinguishable from absolute pitch.
Previously, omitting the reference pitch would have lead to a
default of @code{c'}.  Since that choice was somewhat arbitrary,
recommended usage was to always specify the reference pitch.

@item
A new command @code{\single} can be used for converting a property
override into a tweak to be applied on a single music expression:

@lilypond[quote,verbatim,relative=2]
<a \single\voiceTwoStyle e' a>1
@end lilypond

@item
Two ways of letting graphical objects not appear in the output are
overriding its @code{transparent} property with @code{#t}
(retaining the original spacing) or overriding its @code{stencil}
property with @code{#f} (not using any space at all).  Those two
operations now have the shorthands @code{\hide} and @code{\omit},
respectively.  They can either be given a music expression to
tweak, or the name of a graphical object for which an override
should be created (for specifying both, use @code{\single} on the
override form):

@lilypond[quote,verbatim]
\new Staff \with { \omit Clef }
\relative c'' <a e' \hide a>1
@end lilypond

@item
A new command @code{\temporary} can be applied to overrides in
order to not have them replace previous property settings.  If a
@code{\revert} is applied to the same property subsequently, the
previous setting reappears:

@lilypond[quote,verbatim,relative=2]
\override NoteHead.color = #red c4
\override NoteHead.color = #green d
\revert NoteHead.color e2
\override NoteHead.color = #red c4
\temporary\override NoteHead.color = #green d
\revert NoteHead.color e
\revert NoteHead.color c
@end lilypond

This is mainly useful for writing music functions that need to
have some property changed just for the duration of the function.

@item
@code{\tag}, @code{\removeWithTag}, and @code{\keepWithTag} can
now accept a list of symbols rather than just a single symbol for
marking, removing, and keeping music with any of multiple tags.
This is particularly important for @code{\keepWithTag} since one
cannot achieve the same effect by using multiple consecutive
@code{\keepWithTag} commands.

@item
The @samp{-d old-relative} option has been removed.  Not actually
accessible from the command line any more, its remaining use was
for interpretating @code{\relative} in LilyPond files converted
automatically from version@tie{}1.8 or older.  It is unclear how
much of this was actually still operative.

@item
The meaning of @code{instrumentTransposition} has been reversed.
After
@example
\set instrumentTransposition = #@{ b #@}
@end example
a written @code{c'} now sounds like @code{b}.  Previously, this
would have been the other way round.  This and the following change
should make dealing with transposing instruments more
straightforward.

@item
The music generated by @code{\set} and @code{\override} commands
is no longer affected by @code{\transpose}.  The main consequence
is that @code{\transpose} will transpose audible/@/concert pitch and
printed pitch by the same amount even when the transposed music
contains @code{\transposition}.  Previously,
@example
\transpose c' f' \transposition bes'
@end example
was equivalent to @code{\transposition f'}.  Now it stays
equivalent to @code{\transposition bes'}.

@item
When checking for collisions, LilyPond no longer treats objects as
rectangles.  Instead, the actual shape of objects is approximated
using an integral-like approach.  This generally results in more
even and snug positioning of objects and systems:

@lilypond[relative=1]
#(ly:set-option 'debug-skylines #t)
\dynamicUp
c'4\f a4\f d\f( f)
a,4\< c c c\!
d4-.\downbow a4^"r'venu..." c \tempo "T1" e
@end lilypond

Previously, the above snippet looked like this:

@lilypond[relative=1]
#(ly:set-option 'debug-skylines #t)
\override Hairpin #'vertical-skylines = #'()
\override DynamicText #'vertical-skylines = #'()
\override TextScript #'vertical-skylines = #'()
\override Score.MetronomeMark #'vertical-skylines = #'()
\override Staff.Clef #'vertical-skylines = #'()
\dynamicUp
c'4\f a4\f d\f( f)
a,4\< c c c\!
d4-.\downbow a4^"r'venu..." c \tempo "T1" e
@end lilypond

Affected objects include @code{Accidentals}, @code{Beams}, @code{Clefs},
@code{Dynamics}, @code{FiguredBass}, @code{Flags}, @code{Glissandos},
@code{Lyrics}, @code{MetronomeMarks}, @code{OttavaBrackets},
@code{Pedals}, @code{RehearsalMarks}, @code{Rests}, @code{Scripts},
@code{TextScripts}, @code{Ties}, @code{Tuplets} and @code{VoltaBrackets}.

@item
Tuplets are now created with the @code{\tuplet} command, which
takes a fraction @code{@var{t}/@var{n}} to specify that @var{t}
notes are played in the time usually allowed for @var{n}. One
@code{\tuplet} command can create several tuplet groups if their
duration is typed after the fraction.
@lilypond[quote,verbatim,relative=2]
\tuplet 3/2 { c8 d e } \tuplet 3/2 { f e d } c2
\tuplet 3/2 4 { c8 d e f e d } c2
@end lilypond
The @code{\times} command with its inverted fraction order
@code{@var{n}/@var{t}} is still available.

@item
Introducing two new markup-commands; @code{\draw-dashed-line} and
@code{\draw-dotted-line}.

@noindent
The dashed-line extends to the whole length given by @var{dest}, if
@code{full-length} is set to @code{#t} (this is the default) without any
space at the beginning or end.  @code{off} will then be altered to fit.
To insist on the given (or default) values of @code{on}, @code{off} use
@code{\override #'(full-length . #f)}.  Manual settings for @code{on},
@code{off} and @code{phase} are possible.

@noindent
The dotted-line always extends to the whole length given by @var{dest},
without any space at the beginning or end.  Manual settings for
@code{off} are possible to get larger or smaller space between the dots.
The given (or default) value of @code{off} will be altered to fit the
line-length.

@lilypond[verbatim,quote]
\markup {
  \draw-dashed-line #'(5.1 . 2.3)
  \override #'(on . 0.3)
  \override #'(off . 0.5)
  \draw-dashed-line #'(5.1 . 2.3)
  \draw-dotted-line #'(5.1 . 2.3)
  \override #'(thickness . 2)
  \override #'(off . 0.2)
  \draw-dotted-line #'(5.1 . 2.3)
}
@end lilypond

@item
Starting with version@tie{}2.17.10, error messages or the
@code{textedit} @acronym{URI} used for point-and-click
functionality specify column numbers starting with@tie{}1 rather
than@tie{}0.  The byte offset (also part of @code{textedit}
@acronym{URI}s) still starts at@tie{}0.

@item
The @code{\clef} command supports optional transposition:
@lilypond[verbatim,quote,relative=1]
\clef "treble_(8)"
c2 c
\clef "bass^[15]"
c2 c
@end lilypond

@item
The LilyPond syntax of dot-separated words @code{Voice.Accidental}
has been made interchangeable with @code{#'(Voice Accidental)}, a
Scheme list of symbols.  As one result, code like
@example
\override Voice.TextSpanner #'(bound-details left text) = "rit."
@end example
is now equivalent to
@example
\override Voice.TextSpanner bound-details.left.text = "rit."
@end example
or even
@example
\override #'(Voice TextSpanner) bound-details.left.text = "rit."
@end example

@item
Grob and grob property path no longer need to be specified as two
separate arguments to commands like @samp{\override} and
@code{\revert}, allowing for the syntax
@example
\override Voice.TextSpanner.bound-details.left.text = "rit."
@end example
Since complementary music functions like @samp{\overrideProperty}
cannot support forms with and without separating space at the same
time, using a single dotted path is now the preferred form.
Specifying grob path and grob property path separately, currently
still supported with @samp{\override} and @samp{\revert} for
compatibility reasons, is deprecated.

@item
Due to words now being accepted as symbol function arguments, the
interfaces of @samp{\accidentalStyle}, @samp{\alterBroken},
@samp{\footnote} and @samp{\tweak} had to be redesigned where
optional symbol arguments were involved.  Please check the
respective music function documentation for details.

@item
Several commands now accept symbol lists (conveniently entered as
dot-separated words) for various kinds of arguments.  These
include @samp{\accidentalStyle}, @samp{\alterBroken},
@samp{\footnote}, @samp{\hide}, @samp{\omit},
@samp{\overrideProperty}, @samp{\shape}, and @samp{\tweak}.

@item
The bar line user interface has changed. Bar glyphs now resemble the
appearance of the bar line, so a left repeat sign has to be coded
as @code{.|:}. The command @code{\defineBarLine} provides an easy way
to define additional bar line styles.

@item
Accidentals in the key signature may be printed in octaves other
than their traditional positions, or in multiple octaves.
@lilypond[quote,relative=0]
\override Staff.KeySignature #'flat-positions = #'((-5 . 5))
\override Staff.KeyCancellation #'flat-positions = #'((-5 . 5))
\clef bass \key es \major es g bes d
\clef treble \bar "||" \key es \major es g bes d
\override Staff.KeySignature #'sharp-positions = #'(2)
\bar "||" \key d \major b fis b2
@end lilypond

@end itemize

@ifhtml
For older news, go to
@uref{http://lilypond.org/doc/v2.16/Documentation/changes/},
@uref{http://lilypond.org/doc/v2.14/Documentation/changes/},
or @uref{../,go back} to the Documentation index.


@end ifhtml

@bye