Guide, node Updating translation committishes..
@end ignore
-@c \version "2.14.0"
+@c \version "2.15.39"
@node Changing defaults
@chapter Changing defaults
options available in LilyPond. It is written as a HTML document,
which is available
@c leave the @uref as one long line.
-@uref{http://@/lilypond@/.org/@/doc/@/stable/@/Documentation/@/user/@/lilypond@/-internals/,on@/-line},
+@uref{http://@/lilypond@/.org/@/doc/@/stable/@/Documentation/@/internals/,on@/-line},
and is also included with the LilyPond documentation package.
Internally, LilyPond uses Scheme (a LISP dialect) to provide
* Modifying context plug-ins::
* Changing context default settings::
* Defining new contexts::
-* Aligning contexts::
+* Context layout order::
@end menu
-
@seealso
Learning Manual:
@rlearning{Contexts and engravers}.
@c TODO Should this be Modifying engravers or Modifying contexts?
-Notation contexts (like @code{Score} and @code{Staff}) not only
-store properties,
-they also contain plug-ins called @q{engravers} that create notation
-elements. For example, the @code{Voice} context contains a
+Notation contexts (like @code{Score} and @code{Staff}) not only store
+properties, they also contain plug-ins called @q{engravers} that create
+notation elements. For example, the @code{Voice} context contains a
@code{Note_heads_engraver} and the @code{Staff} context contains a
-@code{Key_signature_engraver}.
+@code{Key_engraver}.
For a full a description of each plug-in, see
@ifhtml
Modifications can be made to the @code{Score} context or all
@code{Voice} contexts in a similar way.
-@knownissues
-
-It is not possible to collect context changes in a variable and apply
-them to a @code{\context} definition by referring to that variable.
+Context changes can be placed in a variable and applied to a
+@code{\context} definition by prepending the modification with
+@code{\with}:
+@lilypond[quote,verbatim]
+blubb = \with {
+ fontSize = #-4
+ \override Stem #'thickness = #4.0
+ \remove "Time_signature_engraver"
+}
-The @code{\Staff \RemoveEmptyStaves} will overwrite your current
-@code{\Staff} settings. If you wish to change the defaults for a
-staff which uses @code{\Staff \RemoveEmptyStaves}, you must do so
-after calling @code{\Staff \RemoveEmptyStaves}, ie
+bla = \with {
+ fontSize = #3
+ \override Stem #'thickness = #-2.0
+}
-@example
-\layout @{
- \context @{
- \Staff \RemoveEmptyStaves
+melody = \relative c'' {
+ a4 a a a |
+ a4 a a a |
+}
- \override Stem #'thickness = #4.0
- @}
-@}
-@end example
+\score {
+ <<
+ \new Staff <<
+ \melody
+ s1*0^"Small, thicker stems, no time signature"
+ >>
+ \new Staff \bla <<
+ \melody
+ s1*0^"Different"
+ >>
+ >>
+ \layout {
+ \context {
+ \Staff
+ \blubb
+ }
+ }
+}
+@end lilypond
@c TODO: add \with in here.
squashedPosition = #0
\override NoteHead #'style = #'slash
\override Stem #'transparent = ##t
+ \override Flag #'transparent = ##t
\alias Voice
}
\context { \Staff
@example
\override NoteHead #'style = #'slash
\override Stem #'transparent = ##t
+\override Flag #'transparent = ##t
@end example
All these plug-ins have to cooperate, and this is achieved with a
squashedPosition = #0
\override NoteHead #'style = #'slash
\override Stem #'transparent = ##t
+ \override Flag #'transparent = ##t
\alias Voice
@}
@end example
@end example
-@node Aligning contexts
-@subsection Aligning contexts
+@node Context layout order
+@subsection Context layout order
-New contexts may be aligned above or below existing contexts. This
-could be useful in setting up a vocal staff (@rlearning{Vocal ensembles}) and
-in ossia,
+@cindex contexts, layout order
+@funindex \accepts
+@funindex \denies
-@c TODO Better example needed. Ref LM, and expand on it.
+Contexts are normally positioned in a system from top to bottom
+in the order in which they are encountered in the input file. When
+contexts are nested, the outer context will include inner nested
+contexts as specified in the input file, provided the inner contexts
+are included in the outer context's @qq{accepts} list. Nested
+contexts which are not included in the outer context's @qq{accepts}
+list will be repositioned below the outer context rather than nested
+within it.
-@cindex ossia
-@funindex alignAboveContext
-@funindex alignBelowContext
+The @qq{accepts} list of a context can be changed with the
+@code{\accepts} and @code{\denies} commands. @code{\accepts} adds a
+context to the @qq{accepts} list and @code{\denies} removes a context
+from the list. For example, it would not normally be desirable for
+chord names to be nested within a @code{Staff} context, so the
+@code{ChordNames} context is not included by default in the @qq{accepts}
+list of the @code{Staff} context, but if this were to be required it can
+be done:
-@lilypond[quote,ragged-right]
-ossia = { f4 f f f }
-\score{
- \relative c' \new Staff = "main" {
- c4 c c c
- <<
- \new Staff \with { alignAboveContext = #"main" } \ossia
- { d8 f d f d f d f }
- >>
+@lilypond[verbatim,quote]
+\score {
+ \new Staff {
+ c' d' e' f'
+ \chords { d1:m7 b1:min7.5- }
}
}
@end lilypond
-@cindex nested contexts
-@cindex contexts, nested
-
-@funindex \accepts
-@funindex \denies
-
-Contexts like @code{PianoStaff} can contain other contexts
-nested within them. Contexts which are acceptable for nesting
-are defined by the @qq{accepts} list of a context. Contexts
-which are not in this list are placed below the outer context
-in the printed score.
-For example, the @code{PianoStaff} context is defined by default
-to accept @code{Staff} and @code{FiguredBass} contexts within
-it, but not (for example) a @code{Lyrics} context. So in the
-following structure the lyrics are placed below the piano staff
-rather than between the two staves:
-
-@lilypond[verbatim,quote,relative=1]
-\new PianoStaff
-<<
- \new Staff { e4 d c2 }
- \addlyrics { Three blind mice }
+@lilypond[verbatim,quote]
+\score {
\new Staff {
- \clef "bass"
- { c,1 }
+ c' d' e' f'
+ \chords { d1:m7 b1:min7.5- }
}
->>
+ \layout {
+ \context {
+ \Staff
+ \accepts "ChordNames"
+ }
+ }
+}
@end lilypond
-The @qq{accepts} list of a context can be modified to include
-additional nested contexts, so if we wanted the lyrics to appear
-between the two staves we could use:
+@code{\denies} is mainly used when a new context is being based on
+another, but the required nesting differs. For example, the
+@code{VaticanaStaff} context is based on the @code{Staff} context, but
+with the @code{VaticanaVoice} context substituted for the @code{Voice}
+context in the @qq{accepts} list.
-@lilypond[verbatim,quote,relative=1]
-\new PianoStaff \with { \accepts Lyrics }
-<<
- \new Staff { e4 d c2 }
- \addlyrics { Three blind mice }
- \new Staff {
- \clef "bass"
- { c,1 }
- }
->>
-@end lilypond
+Note that a context will be silently created implicitly if a command
+is encountered when there is no suitable context available to
+contain it. This can give rise to unexpected new staves or scores.
+
+@seealso
+Application Usage:
+@rprogram{An extra staff appears}.
+
+Installed Files:
+@file{ly/engraver-init.ly}.
-The opposite of @code{\accepts} is @code{\denies}; this removes a
-context from the @qq{accepts} list.
@node Explaining the Internals Reference
@section Explaining the Internals Reference
-
@menu
* Navigating the program reference::
* Layout interfaces::
@end ignore
@seealso
-Internals:
+Internals Reference:
@rinternals{Backend},
@rinternals{All layout objects},
@rinternals{OverrideProperty},
@rinternals{RevertProperty},
@rinternals{PropertySet}.
-
@knownissues
-
The back-end is not very strict in type-checking object properties.
Cyclic references in Scheme values for properties can cause hangs
or crashes, or both.
-
@node The set command
@subsection The @code{@bs{}set} command
@end ifnothtml
@seealso
-
Internals Reference:
-
@rinternals{Tunable context properties}.
-
@cindex grob properties
@cindex properties, grob
@funindex \override
@end ignore
@seealso
-
Internals Reference:
@rinternals{Backend}
+
@node The tweak command
@subsection The @code{\tweak} command
syntax:
@example
-\tweak #'@code{grob-property} #@code{value}
+\tweak @var{layout-object} #'@var{grob-property} @var{value}
@end example
-The @code{\tweak} command applies to the object that immediately
-follows @code{value} in the music stream.
+Specifying @var{layout-object} is optional.
+The @code{\tweak} command applies to the music object that immediately
+follows @var{value} in the music stream.
@ignore
In some cases, it is possible to take a short-cut for tuning
For the @code{\tweak} command to work, it must
remain immediately adjacent to the object to which it is
to apply after the input file has been converted to a music stream.
-At times, LilyPond may insert additional items into the music stream
-during the parsing process. For example, when a note that is not
-explicitly part of a chord will be placed in a chord by LilyPond,
-so notes to be modified with @code{\tweak} must be placed inside
-a chord construct:
+Tweaking a whole chord does not do anything since its music event
+only acts as a container, and all layout objects are created from events
+inside of the @code{EventChord}:
@lilypond[relative=2,verbatim,quote]
\tweak #'color #red c4
-<\tweak #'color #red c>4
+\tweak #'color #red <c e>4
+<\tweak #'color #red c e>4
@end lilypond
-The @code{\tweak} command cannot be used to modify any item
-that does not appear explicitly in the input file. In particular
-it cannot be used to modify stems,
-beams or accidentals directly, since these are generated later by
-note heads, rather than by music elements in the input stream.
-Nor can @code{\tweak} be used to modify clefs or time
+The simple @code{\tweak} command cannot be used to modify any object
+that is not directly created from the input. In particular
+it will not affect stems, automatic
+beams or accidentals, since these are generated later by
+\@code{NoteHead} layout objects rather than by music elements in the
+input stream.
+
+Such indirectly created layout objects can be tweaked using the explicit
+form of the @code{\tweak} command:
+
+@lilypond[relative=2,verbatim,quote]
+\tweak Stem #'color #red
+\tweak Beam #'color #green c8 e
+<c e \tweak Accidental #'font-size #-3 ges>4
+@end lilypond
+
+@code{\tweak} cannot be used to modify clefs or time
signatures, since these become separated from any preceding
@code{\tweak} command in the input stream by the automatic
insertion of extra elements required to specify the context.
in determining how to adjust the input to make a @code{\tweak}
apply.
-
@seealso
Learning Manual:
@rlearning{Tweaking methods}.
-Extending:
+Extending LilyPond:
@rextend{Displaying music expressions}.
-
@knownissues
-@cindex tweaks in a variable
-The @code{\tweak} command cannot be used inside a variable.
-
-@cindex tweaks in lyrics
-The @code{\tweak} commands cannot be used in @code{\lyricmode}.
-
@cindex tweaking control points
@cindex control points, tweaking
The @code{\tweak} command will apply to only the first of several
generated ties in a chord.
+
@node set versus override
@subsection @code{\set} vs. @code{\override}
@menu
* Input modes::
* Direction and placement::
-* Context layout order::
* Distances and measurements::
* Staff symbol properties::
* Spanners::
@strong{The direction property}
-The position or direction of many layout objects is controlled
-by the @code{direction} property.
+The position or direction of many layout objects is controlled by the
+@code{direction} property.
-The value of the @code{direction} property may be
-set to @code{1}, meaning @qq{up} or @qq{above}, or to @w{@code{-1}},
-meaning @qq{down} or @qq{below}. The symbols @code{UP} and
-@code{DOWN} may be used instead of @code{1} and @w{@code{-1}}
-respectively. The default direction may be specified by setting
-@code{direction} to @code{0} or @code{CENTER}. Alternatively,
-in many cases predefined commands
-exist to specify the direction. These are all of the form
+The value of the @code{direction} property may be set to @code{1},
+meaning @qq{up} or @qq{above}, or to @w{@code{-1}}, meaning @qq{down} or
+@qq{below}. The symbols @code{UP} and @code{DOWN} may be used instead
+of @code{1} and @w{@code{-1}} respectively. The default direction may
+be specified by setting @code{direction} to @code{0} or @code{CENTER}.
+Alternatively, in many cases predefined commands exist to specify the
+direction. These are of the form
-@noindent
-@code{\xxxUp}, @code{xxxDown}, @code{xxxNeutral}
+@example
+@code{\xxxUp}, @code{\xxxDown} or @code{\xxxNeutral}
+@end example
@noindent
-where @code{xxxNeutral} means @qq{use the default direction}.
+where @code{\xxxNeutral} means @qq{use the default} direction.
See @rlearning{Within-staff objects}.
-In a few cases, arpeggio being the only common example, the value
-of the @code{direction} property specifies whether the object
-is to be placed to the right or left of the parent object. In
-this case @w{@code{-1}} or @code{LEFT} means @qq{to the left} and
-@code{1} or @code{RIGHT} means @qq{to the right}. @code{0}
-or @code{CENTER} means @qq{use the default} direction, as before.
+In a few cases, arpeggio for example, the value of the @code{direction}
+property can specify whether the object is to be placed to the right or
+left of the parent. In this case @w{@code{-1}} or @code{LEFT} means
+@qq{to the left} and @code{1} or @code{RIGHT} means @qq{to the right}.
+@code{0} or @code{CENTER} means @qq{use the default} direction.
@ignore
These all have side-axis set to #X
TrillPitchGroup - not tried
@end ignore
-These indications affect all notes until they are cancelled.
+These indications affect all notes until they are canceled.
@lilypond[verbatim,quote,relative=2]
c2( c)
c2( c)
@end lilypond
-
-@node Context layout order
-@subsection Context layout order
-
-@cindex contexts, layout order
-
-Contexts are normally positioned in a system from top to bottom
-in the order in which they are encountered in the input file. When
-contexts are nested, the outer context will include inner nested
-contexts as specified in the input file, provided the inner contexts
-are included in the outer context's @qq{accepts} list. Nested
-contexts which are not included in the outer context's @qq{accepts}
-list will be repositioned below the outer context rather than nested
-within it.
-
-Note that a context will be silently created implicitly if a command
-is encountered when there is no suitable context available to
-contain it. This can give rise to unexpected new staves or scores.
-
-The default order in which contexts are laid out and the
-@qq{accepts} list can be changed, see @ref{Aligning contexts}.
+In polyphonic music, it is generally better to specify an explicit
+@code{voice} than change an object's direction. For more information.
+See @ref{Multiple voices}.
@seealso
-Usage Manual:
-@rprogram{An extra staff appears}.
+Learning Manual:
+@rlearning{Within-staff objects}.
+
+Notation Reference:
+@ref{Multiple voices}.
@node Distances and measurements
@code{staff-space}. For an explanation and an example of its use,
see @rlearning{Length and thickness of objects}.
-
@seealso
Learning Manual:
@rlearning{Length and thickness of objects}.
\startTextSpan with \stopTextSpan, nor is it necessary to close
hairpins with @code{\!}.
-
@seealso
Internals Reference:
@rinternals{TextSpanner},
property controls both the clef symbol and any octavation symbol
associated with it.
-
@seealso
Learning Manual:
-@rlearning{Visibility and color of objects}
+@rlearning{Visibility and color of objects}.
@node Line styles
* Vertical grouping of grobs::
* Modifying stencils::
* Modifying shapes::
+* Unpure-pure containers::
@end menu
-
@seealso
Learning Manual:
@rlearning{Tweaking output},
@ref{Explaining the Internals Reference},
@ref{Modifying properties}.
+Extending LilyPond:
+@rextend{Interfaces for programmers}.
+
Installed Files:
@file{scm/define-grobs.scm}.
Snippets:
@rlsr{Tweaks and overrides}.
-Extending:
-@rextend{Interfaces for programmers}.
-
Internals Reference:
@rinternals{All layout objects}.
for positioning rehearsal marks on such objects.
@seealso
-@ref{Using the break-alignable-interface},
+Notation Reference:
+@ref{Using the break-alignable-interface}.
+
+Extending LilyPond:
@rextend{Callback functions}.
@menu
@c TODO Add inserting Postscript or ref to later
-
@seealso
Notation Reference:
@ref{Graphic notation inside markup},
Internals Reference:
@rinternals{TieColumn}.
+@cindex Scheme, pure containers
+@cindex Scheme, unpure containers
+@cindex pure containers, Scheme
+@cindex unpure containers, Scheme
+@cindex horizontal spacing, overriding
+
+
+@node Unpure-pure containers
+@subsection Unpure-pure containers
+
+Unpure-pure containers are useful for overriding @emph{Y-axis} spacing
+calculations - specifically @code{Y-offset} and @code{Y-extent} - with a
+Scheme function instead of a literal (i.e. a number or pair).
+
+For certain grobs, the @code{Y-extent} is based on the @code{stencil}
+property, overriding the stencil property of one of these will
+require an additional @code{Y-extent} override with an unpure-pure
+container. When a function overrides a @code{Y-offset} and/or
+@code{Y-extent} it is assumed that this will trigger line breaking
+calculations too early during compilation. So the function is not
+evaluated at all (usually returning a value of @samp{0} or
+@samp{'(0 . 0)}) which can result in collisions. A @q{pure} function
+will not affect properties, objects or grob suicides and therefore will
+always have its Y-axis-related evaluated correctly.
+
+Currently, there are about thirty functions that are already considered
+@q{pure} and Unpure-pure containers are a way to set functions not on
+this list as @q{pure}. The @q{pure} function is evaluated @emph{before}
+any line-breaking and so the horizontal spacing can be adjusted
+@q{in time}. The @q{unpure} function is then evaluated @emph{after}
+line breaking.
+
+@warning{As it is difficult to always know which functions are on this
+list we recommend that any @q{pure} functions you create do not use
+@code{Beam} or @code{VerticalAlignment} grobs.}
+
+An unpure-pure container is constructed as follows;
+
+@code{(ly:make-unpure-pure-container f0 f1)}
+
+where @code{f0} is a function taking @var{n} arguments (@var{n >= 1})
+and the first argument must always be the grob. This is the function
+that gives the actual result. @var{f1} is the function being labeled
+as @q{pure} that takes @var{n + 2} arguments. Again, the first argument
+must always still be the grob but the second and third are @q{start}
+and @q{end} arguments.
+
+@var{start} and @var{end} are, for all intents and purposes, dummy
+values that only matter for @code{Spanners} (i.e @code{Hairpin} or
+@code{Beam}), that can return different height estimations based on a
+starting and ending column.
+
+The rest are the other arguments to the first function (which
+may be none if @var{n = 1}).
+
+The results of the second function are used as an approximation of the
+value needed which is then used by the first function to get the real
+value which is then used for fine-tuning much later during the spacing
+process.
+
+@lilypond[verbatim,quote,ragged-right]
+#(define (square-line-circle-space grob)
+(let* ((pitch (ly:event-property (ly:grob-property grob 'cause) 'pitch))
+ (notename (ly:pitch-notename pitch)))
+ (if (= 0 (modulo notename 2))
+ (make-circle-stencil 0.5 0.0 #t)
+ (make-filled-box-stencil '(0 . 1.0)
+ '(-0.5 . 0.5)))))
+
+squareLineCircleSpace = {
+ \override NoteHead #'stencil = #square-line-circle-space
+}
+
+smartSquareLineCircleSpace = {
+ \squareLineCircleSpace
+ \override NoteHead #'Y-extent =
+ #(ly:make-unpure-pure-container
+ ly:grob::stencil-height
+ (lambda (grob start end) (ly:grob::stencil-height grob)))
+}
+
+\new Voice \with { \remove "Stem_engraver" }
+\relative c'' {
+ \squareLineCircleSpace
+ cis4 ces cisis c
+ \smartSquareLineCircleSpace
+ cis4 ces cisis c
+}
+@end lilypond
+
+In the first measure, without the unpure-pure container, the spacing
+engine does not know the width of the note head and lets it collide with
+the accidentals. In the second measure, with unpure-pure containers,
+the spacing engine knows the width of the note heads and avoids the
+collision by lengthening the line accordingly.
+
+Usually for simple calculations nearly-identical functions for both the
+@q{unpure} and @q{pure} parts can be used, by only changing the number
+of arguments passed to, and the scope of, the function.
+
+@warning{If a function is labeled as @q{pure} and it turns out not to
+be, the results can be unexpected.}
+
@node Using music functions
@section Using music functions
must return @code{#t}.
@item @code{@var{@dots{}music@dots{}}}
-@tab normal LilyPond input, using @code{$} to reference arguments
-(eg. @samp{$arg1}).
+@tab normal LilyPond input, using @code{$} (in places where only
+Lilypond constructs are allowed) or @code{#} (to use it as a Scheme
+value or music function argument) to reference arguments
+(eg. @samp{#arg1}).
@end multitable
-
The @code{parser} and @code{location} arguments are mandatory, and
are used in some advanced situations as described in the
@q{Extending} manual (see @rextend{Music functions}). For
@example
boolean?
cheap-list? @emph{(use instead of }@q{list?}@emph{ for faster processing)}
+ly:duration?
ly:music?
+ly:pitch?
markup?
number?
pair?
@ref{Predefined type predicates}. User-defined type predicates
are also allowed.
-
@seealso
-
Notation Reference:
@ref{Predefined type predicates}.
-Extending:
+Extending Lilypond:
@rextend{Music functions}.
Installed Files:
(parser location padding)
(number?)
#{
- \once \override TextScript #'padding = $padding
+ \once \override TextScript #'padding = #padding
#})
\relative c''' {
In addition to numbers, we can use music expressions such
as notes for arguments to music functions:
-@c TODO: use a better example (the music argument is redundant).
-
@lilypond[quote,verbatim,ragged-right]
custosNote =
#(define-music-function
(parser location note)
(ly:music?)
#{
- \once \override Voice.NoteHead #'stencil =
- #ly:text-interface::print
- \once \override Voice.NoteHead #'text =
- \markup \musicglyph #"custodes.mensural.u0"
- \once \override Voice.Stem #'stencil = ##f
+ \tweak NoteHead #'stencil #ly:text-interface::print
+ \tweak NoteHead #'text
+ \markup \musicglyph #"custodes.mensural.u0"
+ \tweak Stem #'stencil ##f
$note
#})
tempoPadded =
#(define-music-function
(parser location padding tempotext)
- (number? string?)
+ (number? markup?)
#{
- \once \override Score.MetronomeMark #'padding = $padding
- \tempo \markup { \bold $tempotext }
+ \once \override Score.MetronomeMark #'padding = #padding
+ \tempo \markup { \bold #tempotext }
#})
\relative c'' {
\tempo \markup { "Low tempo" }
c4 d e f g1
- \tempoPadded #4.0 #"High tempo"
+ \tempoPadded #4.0 "High tempo"
g4 f e d c1
}
@end lilypond
projects / lilypond.git / blobdiff