@c -*- coding: utf-8; mode: texinfo; -*-
+@c This file is part of lilypond.tely
+@ignore
+ Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
+
+ When revising a translation, copy the HEAD committish of the
+ version that you are working on. See TRANSLATION for details.
+@end ignore
+
@node Changing defaults
@chapter Changing defaults
The purpose of LilyPond's design is to provide the finest output
quality as a default. Nevertheless, it may happen that you need to
change this default layout. The layout is controlled through a large
-number of proverbial ``knobs and switches.'' This chapter does not
+number of proverbial @q{knobs and switches.} This chapter does not
list each and every knob. Rather, it outlines what groups of controls
are available and explains how to lookup which knob to use for a
particular effect.
That manual
lists all different variables, functions and options available in
LilyPond. It is written as a HTML document, which is available
-@uref{http://@/lilypond@/.org/@/doc/@/v2.8/@/Documentation/@/user/@/
-lilypond@/-internals/,on@/-line},
+@c leave the @uref as one long line.
+@uref{http://@/lilypond@/.org/@/doc/@/stable/@/Documentation/@/user/@/lilypond@/-internals/,on@/-line},
but is also included with the LilyPond documentation package.
There are four areas where the default settings may be changed:
Output: changing the appearance of individual
objects. For example, changing stem directions or the location of
subscripts.
-
+
@item
Context: changing aspects of the translation from music events to
-notation. For example, giving each staff a separate time signature.
-
+notation. For example, giving each staff a separate time signature.
+
@item
-Global layout: changing the appearance of the spacing, line
+Page layout: changing the appearance of the spacing, line
breaks, and page dimensions. These modifications are discussed
-in @ref{Global issues}.
+in @ref{Non-musical notation}, and @ref{Spacing issues}.
@end itemize
Internally, LilyPond uses Scheme (a LISP dialect) to provide
infrastructure. Overriding layout decisions in effect accesses the
program internals, which requires Scheme input. Scheme elements are
introduced in a @code{.ly} file with the hash mark
-@code{#}.@footnote{@ref{Scheme tutorial} contains a short tutorial
+@code{#}.@footnote{@ref{Scheme tutorial}, contains a short tutorial
on entering numbers, lists, strings, and symbols in Scheme.}
* The \override command::
@end menu
-
+
@node Automatic notation
@section Automatic notation
Common rules for typesetting accidentals have been placed in a
function. This function is called as follows
-@cindex @code{set-accidental-style}
+@funindex set-accidental-style
+@example
+#(set-accidental-style 'STYLE)
+@end example
+
+@c TODO: check the context stuff below
+@c -does it *really* work?
+@c -the default contexts as specified in
+@c scm/music-function.scm seem to be different -vv
+
+Optionally, the function can take two arguments: the name of the
+accidental style, and an optional argument that denotes the context that
+should be changed:
+
@example
#(set-accidental-style 'STYLE #('CONTEXT#))
@end example
-The function can take two arguments: the name of the accidental style,
-and an optional argument that denotes the context that should be
-changed. If no context name is supplied, @code{Staff} is the default,
+If no context name is supplied, @code{Staff} is the default,
but you may wish to apply the accidental style to a single @code{Voice}
instead.
-@c TODO: we should create a very clear example, and show every
-@c accidental style on that example (with the example specially
-@c constructed so that it illustrates all the differences). -gp
+The following accidental styles are supported:
-The following accidental styles are supported
@table @code
@item default
This is the default typesetting behavior. It corresponds
remembered to the end of the measure in which they occur and
only on their own octave.
+@lilypond[quote,ragged-right]
+musicA = { << \relative { cis'8 fis, d'4 <a cis>8 f bis4 | cis2. <c, g'>4 | } \\
+ \relative { ais'2 cis, | fis8 b a4 cis2 | } >> }
+
+musicB = { \clef bass \new Voice { \voiceTwo \relative { < fis, a cis>4
+ \change Staff = up cis' \change Staff = down <fis, a>
+ \change Staff = up dis' | \change Staff = down <fis, a cis>4 gis
+ <f a d>2 | } }}
+
+\score {
+ \new PianoStaff {
+ << \context Staff = "up" {
+ %#(set-accidental-style 'default)
+ \musicA }
+ \context Staff = "down"{
+ %#(set-accidental-style 'default)
+ \musicB } >> }
+ \header { piece = \markup {\fill-line { \fontsize #3 "'default" }}}
+}
+@end lilypond
+
@item voice
The normal behavior is to remember the accidentals on
Staff-level. This variable, however, typesets accidentals
individually for each voice. Apart from that, the rule is similar to
@code{default}.
+@example
+ \new Staff <<
+ #(set-accidental-style 'voice)
+ @{ @dots{} @}
+ >>
+@end example
+
As a result, accidentals from one voice do not get canceled in other
-voices, which is often an unwanted result
-
-@lilypond[quote,ragged-right,relative=1,fragment,verbatim]
-\new Staff <<
- #(set-accidental-style 'voice)
- <<
- { es g } \\
- { c, e }
->> >>
+voices, which is often an unwanted result: in the following example, it
+is hard to determine whether the second @samp{a} should be played
+natural or sharp.
+
+@lilypond[quote,ragged-right]
+musicA = { << \relative { cis'8 fis, d'4 <a cis>8 f bis4 | cis2. <c, g'>4 | } \\
+ \relative { ais'2 cis, | fis8 b a4 cis2 | } >> }
+
+musicB = { \clef bass \new Voice { \voiceTwo \relative { < fis, a cis>4
+ \change Staff = up cis' \change Staff = down <fis, a>
+ \change Staff = up dis' | \change Staff = down <fis, a cis>4 gis
+ <f a d>2 | } }}
+
+\score {
+ \new PianoStaff {
+ << \context Staff = "up" {
+ #(set-accidental-style 'voice)
+ \musicA }
+ \context Staff = "down"{
+ #(set-accidental-style 'voice)
+ \musicB } >> }
+ \header { piece = \markup {\fill-line { \fontsize #3 "'voice" }}}
+}
@end lilypond
The @code{voice} option should be used if the voices
should be used instead.
@item modern
-@cindex @code{modern} style accidentals
+@funindex modern style accidentals
This rule corresponds to the common practice in the 20th century. This rule
prints the same accidentals as @code{default}, but temporary
accidentals also are canceled in other octaves. Furthermore,
in the same octave, they also get canceled in the following
-measure
+measure: in the following example, notice the two natural signs which appear
+in the second bar of the upper staff.
-@lilypond[quote,ragged-right,fragment,verbatim]
-#(set-accidental-style 'modern)
-cis' c'' cis'2 | c'' c'
+@lilypond[quote,ragged-right]
+musicA = { << \relative { cis'8 fis, d'4 <a cis>8 f bis4 | cis2. <c, g'>4 | } \\
+ \relative { ais'2 cis, | fis8 b a4 cis2 | } >> }
+
+musicB = { \clef bass \new Voice { \voiceTwo \relative { < fis, a cis>4
+ \change Staff = up cis' \change Staff = down <fis, a>
+ \change Staff = up dis' | \change Staff = down <fis, a cis>4 gis
+ <f a d>2 | } }}
+
+\score {
+ \new PianoStaff {
+ << \context Staff = "up" {
+ #(set-accidental-style 'modern)
+ \musicA }
+ \context Staff = "down"{
+ #(set-accidental-style 'modern)
+ \musicB } >> }
+ \header { piece = \markup {\fill-line { \fontsize #3 "'modern" }}}
+}
@end lilypond
@item @code{modern-cautionary}
-@cindex @code{modern-cautionary}
-This rule is similar to @code{modern}, but the ``extra'' accidentals
+@funindex modern-cautionary
+This rule is similar to @code{modern}, but the @q{extra} accidentals
(the ones not typeset by @code{default}) are typeset as cautionary
-accidentals. They are printed in reduced size or with parentheses
-@lilypond[quote,ragged-right,fragment,verbatim]
-#(set-accidental-style 'modern-cautionary)
-cis' c'' cis'2 | c'' c'
+accidentals. They are printed in reduced size or (by default)
+with parentheses -- this can be set by definig the @code{cautionary-style}
+property of the @internalsref{AccidentalSuggestion} object.
+
+@lilypond[quote,ragged-right]
+musicA = { << \relative { cis'8 fis, d'4 <a cis>8 f bis4 | cis2. <c, g'>4 | } \\
+ \relative { ais'2 cis, | fis8 b a4 cis2 | } >> }
+
+musicB = { \clef bass \new Voice { \voiceTwo \relative { < fis, a cis>4
+ \change Staff = up cis' \change Staff = down <fis, a>
+ \change Staff = up dis' | \change Staff = down <fis, a cis>4 gis
+ <f a d>2 | } }}
+
+\score {
+ \new PianoStaff {
+ << \context Staff = "up" {
+ #(set-accidental-style 'modern-cautionary)
+ \musicA }
+ \context Staff = "down"{
+ #(set-accidental-style 'modern-cautionary)
+ \musicB } >> }
+ \header { piece = \markup {\fill-line { \fontsize #3 "'modern-cautionary" }}}
+}
@end lilypond
-@cindex @code{modern-voice}
+@funindex modern-voice
@item modern-voice
This rule is used for multivoice accidentals to be read both by musicians
playing one voice and musicians playing all voices. Accidentals are
typeset for each voice, but they @emph{are} canceled across voices in
the same @internalsref{Staff}.
-@cindex @code{modern-voice-cautionary}
+@lilypond[quote,ragged-right]
+musicA = { << \relative { cis'8 fis, d'4 <a cis>8 f bis4 | cis2. <c, g'>4 | } \\
+ \relative { ais'2 cis, | fis8 b a4 cis2 | } >> }
+
+musicB = { \clef bass \new Voice { \voiceTwo \relative { < fis, a cis>4
+ \change Staff = up cis' \change Staff = down <fis, a>
+ \change Staff = up dis' | \change Staff = down <fis, a cis>4 gis
+ <f a d>2 | } }}
+
+\score {
+ \new PianoStaff {
+ << \context Staff = "up" {
+ #(set-accidental-style 'modern-voice)
+ \musicA }
+ \context Staff = "down"{
+ #(set-accidental-style 'modern-voice)
+ \musicB } >> }
+ \header { piece = \markup {\fill-line { \fontsize #3 "'modern-voice" }}}
+}
+@end lilypond
+
+@funindex modern-voice-cautionary
@item modern-voice-cautionary
This rule is the same as @code{modern-voice}, but with the extra
accidentals (the ones not typeset by @code{voice}) typeset
@code{default} @emph{are} typeset by this variable,
some of them are typeset as cautionaries.
+@lilypond[quote,ragged-right]
+musicA = { << \relative { cis'8 fis, d'4 <a cis>8 f bis4 | cis2. <c, g'>4 | } \\
+ \relative { ais'2 cis, | fis8 b a4 cis2 | } >> }
+
+musicB = { \clef bass \new Voice { \voiceTwo \relative { < fis, a cis>4
+ \change Staff = up cis' \change Staff = down <fis, a>
+ \change Staff = up dis' | \change Staff = down <fis, a cis>4 gis
+ <f a d>2 | } }}
+
+\score {
+ \new PianoStaff {
+ << \context Staff = "up" {
+ #(set-accidental-style 'modern-voice-cautionary)
+ \musicA }
+ \context Staff = "down"{
+ #(set-accidental-style 'modern-voice-cautionary)
+ \musicB } >> }
+ \header { piece = \markup {\fill-line { \fontsize #3 "'modern-voice-cautionary" }}}
+}
+@end lilypond
+
@item piano
-@cindex @code{piano} accidentals
-This rule reflects 20th century practice for piano notation. Very similar to
-@code{modern} but accidentals also get canceled
+@funindex piano accidentals
+This accidental style takes place in a GrandStaff context. However, you have to
+explicitly set it for @emph{each} individual Staff of the GrandStaff:
+
+@example
+\new GrandStaff @{ <<
+ \new Staff = "up" @{ <<
+ #(set-accidental-style 'piano)
+ @{ @dots{} @}
+ >> @}
+ \new Staff = "down"@{ <<
+ #(set-accidental-style 'piano)
+ @{ @dots{} @}
+ >> @}
+>> @}
+@end example
+
+This rule reflects 20th century practice for piano notation. Its behavior is very
+similar to @code{modern} style, but here accidentals also get canceled
across the staves in the same @internalsref{GrandStaff} or
@internalsref{PianoStaff}.
+@lilypond[quote,ragged-right]
+musicA = { << \relative { cis'8 fis, d'4 <a cis>8 f bis4 | cis2. <c, g'>4 | } \\
+ \relative { ais'2 cis, | fis8 b a4 cis2 | } >> }
+
+musicB = { \clef bass \new Voice { \voiceTwo \relative { < fis, a cis>4
+ \change Staff = up cis' \change Staff = down <fis, a>
+ \change Staff = up dis' | \change Staff = down <fis, a cis>4 gis
+ <f a d>2 | } }}
+
+\score {
+ \new PianoStaff {
+ << \context Staff = "up" {
+ #(set-accidental-style 'piano)
+ \musicA }
+ \context Staff = "down"{
+ #(set-accidental-style 'piano)
+ \musicB } >> }
+ \header { piece = \markup {\fill-line { \fontsize #3 "'piano" }}}
+}
+@end lilypond
+
@item piano-cautionary
-@cindex @code{#(set-accidental-style 'piano-cautionary)}
+@funindex #(set-accidental-style 'piano-cautionary)
Same as @code{#(set-accidental-style 'piano)} but with the extra
accidentals typeset as cautionaries.
+@lilypond[quote,ragged-right]
+musicA = { << \relative { cis'8 fis, d'4 <a cis>8 f bis4 | cis2. <c, g'>4 | } \\
+ \relative { ais'2 cis, | fis8 b a4 cis2 | } >> }
+
+musicB = { \clef bass \new Voice { \voiceTwo \relative { < fis, a cis>4
+ \change Staff = up cis' \change Staff = down <fis, a>
+ \change Staff = up dis' | \change Staff = down <fis, a cis>4 gis
+ <f a d>2 | } }}
+
+\score {
+ \new PianoStaff {
+ << \context Staff = "up" {
+ #(set-accidental-style 'piano-cautionary)
+ \musicA }
+ \context Staff = "down"{
+ #(set-accidental-style 'piano-cautionary)
+ \musicB } >> }
+ \header { piece = \markup {\fill-line { \fontsize #3 "'piano-cautionary" }}}
+}
+@end lilypond
+
@item no-reset
-@cindex @code{no-reset} accidental style
+@funindex no-reset accidental style
This is the same as @code{default} but with accidentals lasting
-``forever'' and not only until the next measure
-@lilypond[quote,ragged-right,fragment,verbatim,relative=1]
-#(set-accidental-style 'no-reset)
-c1 cis cis c
+@q{forever} and not only until the next measure:
+@lilypond[quote,ragged-right]
+musicA = { << \relative { cis'8 fis, d'4 <a cis>8 f bis4 | cis2. <c, g'>4 | } \\
+ \relative { ais'2 cis, | fis8 b a4 cis2 | } >> }
+
+musicB = { \clef bass \new Voice { \voiceTwo \relative { < fis, a cis>4
+ \change Staff = up cis' \change Staff = down <fis, a>
+ \change Staff = up dis' | \change Staff = down <fis, a cis>4 gis
+ <f a d>2 | } }}
+
+\score {
+ \new PianoStaff {
+ << \context Staff = "up" {
+ #(set-accidental-style 'no-reset)
+ \musicA }
+ \context Staff = "down"{
+ #(set-accidental-style 'no-reset)
+ \musicB } >> }
+ \header { piece = \markup {\fill-line { \fontsize #3 "'no-reset" }}}
+}
@end lilypond
@item forget
This is sort of the opposite of @code{no-reset}: Accidentals
-are not remembered at all---and hence all accidentals are
+are not remembered at all -- and hence all accidentals are
typeset relative to the key signature, regardless of what was
before in the music
-@lilypond[quote,ragged-right,fragment,verbatim,relative=1]
-#(set-accidental-style 'forget)
-\key d\major c4 c cis cis d d dis dis
+@lilypond[quote,ragged-right]
+musicA = { << \relative { cis'8 fis, d'4 <a cis>8 f bis4 | cis2. <c, g'>4 | } \\
+ \relative { ais'2 cis, | fis8 b a4 cis2 | } >> }
+
+musicB = { \clef bass \new Voice { \voiceTwo \relative { < fis, a cis>4
+ \change Staff = up cis' \change Staff = down <fis, a>
+ \change Staff = up dis' | \change Staff = down <fis, a cis>4 gis
+ <f a d>2 | } }}
+
+\score {
+ \new PianoStaff {
+ << \context Staff = "up" {
+ #(set-accidental-style 'forget)
+ \musicA }
+ \context Staff = "down"{
+ #(set-accidental-style 'forget)
+ \musicB } >> }
+ \header { piece = \markup {\fill-line { \fontsize #3 "'forget" }}}
+}
@end lilypond
@end table
@seealso
Program reference: @internalsref{Accidental_engraver},
-@internalsref{Accidental}, and @internalsref{AccidentalPlacement}.
+@internalsref{Accidental}, @internalsref{AccidentalSuggestion} and @internalsref{AccidentalPlacement}.
@refbugs
@node Setting automatic beam behavior
@subsection Setting automatic beam behavior
-@cindex @code{autoBeamSettings}
-@cindex @code{(end * * * *)}
-@cindex @code{(begin * * * *)}
+@funindex autoBeamSettings
+@funindex (end * * * *)
+@funindex (begin * * * *)
@cindex automatic beams, tuning
@cindex tuning automatic beaming
this rule should apply. Set @code{n} and @code{m} to @code{'*'}
to have this apply in any time signature.
-@item @code{a/b} is the position in the bar at which the beam should
+@item @code{a/b} is the position in the bar at which the beam should
begin/end.
@item @code{context} is optional, and it specifies the context at which
3/8 and on the fourth beat of the measure (after 3/4, that is 2 times
3/8, has passed within the measure).
+If any unexpected beam behaviour occurs, check the default automatic beam
+settings in @file{scm/@/auto@/-beam@/.scm}
+for possible interference, because the beam
+endings defined there will still apply on top of your own overrides. Any
+unwanted endings in the default vales must be reverted for your time
+signature(s).
+
+For example, to typeset @code{(3 4 3 2)}-beam endings in 12/8, begin
+with
+
+@example
+%%% revert default values in scm/auto-beam.scm regarding 12/8 time
+#(revert-auto-beam-setting '(end * * 12 8) 3 8)
+#(revert-auto-beam-setting '(end * * 12 8) 3 4)
+#(revert-auto-beam-setting '(end * * 12 8) 9 8)
+
+%%% your new values
+#(override-auto-beam-setting '(end 1 8 12 8) 3 8)
+#(override-auto-beam-setting '(end 1 8 12 8) 7 8)
+#(override-auto-beam-setting '(end 1 8 12 8) 10 8)
+@end example
+
@cindex automatic beam generation
@cindex autobeam
-@cindex @code{autoBeaming}
+@funindex autoBeaming
@cindex lyrics
If beams are used to indicate melismata in songs, then automatic
@refcommands
-@cindex @code{\autoBeamOff}
+@funindex \autoBeamOff
@code{\autoBeamOff},
-@cindex @code{\autoBeamOn}
+@funindex \autoBeamOn
@code{\autoBeamOn}.
+@commonprop
+
+Beaming patterns may be altered with the @code{beatGrouping} property,
+
+@lilypond[quote,verbatim,relative=2,fragment,ragged-right]
+\time 5/16
+\set beatGrouping = #'(2 3)
+c8[^"(2+3)" c16 c8]
+\set beatGrouping = #'(3 2)
+c8[^"(3+2)" c16 c8]
+@end lilypond
+
@refbugs
@node Interpretation contexts
@section Interpretation contexts
+This section describes what contexts are, and how to modify them.
+
+@menu
+* Contexts explained::
+* Creating contexts::
+* Changing context properties on the fly::
+* Modifying context plug-ins::
+* Layout tunings within contexts::
+* Changing context default settings::
+* Defining new contexts::
+* Aligning contexts::
+* Vertical grouping of grobs::
+@end menu
+
+
+@node Contexts explained
+@subsection Contexts explained
+
When music is printed, a lot of notational elements must be added to the
-input. For example, compare the input and output of the following example:
+output. For example, compare the input and output of the following example:
@lilypond[quote,verbatim,relative=2,fragment]
cis4 cis2. g4
example: a @context{Staff} can contain many @context{Voice}s, and a
@context{Score} can contain many @context{Staff} contexts.
+@quotation
+@image{context-example,5cm,,}
+@end quotation
+
Each context has the responsibility for enforcing some notation rules,
creating some notation objects and maintaining the associated
properties. For example, the @context{Voice} context may introduce an
@ifhtml
@internalsref{Contexts}.
@end ifhtml
-@ifnothtml
+@ifnothtml
Translation @arrow{} Context.
@end ifnothtml
@c [TODO: describe propagation]
-@menu
-* Creating contexts::
-* Changing context properties on the fly::
-* Modifying context plug-ins::
-* Layout tunings within contexts::
-* Changing context default settings::
-* Defining new contexts::
-@end menu
-
@node Creating contexts
@subsection Creating contexts
The easiest command is @code{\new}, and it also the quickest to type.
It is prepended to a music expression, for example
-@cindex @code{\new}
+@funindex \new
@cindex new contexts
@cindex Context, creating
interpreting the @var{music expression} with that.
A practical application of @code{\new} is a score with many
-staves. Each part that should be on its own staff, is preceded with
+staves. Each part that should be on its own staff, is preceded with
@code{\new Staff}.
@lilypond[quote,verbatim,relative=2,ragged-right,fragment]
context already earlier with the same name.
-@cindex @code{\context}
+@funindex \context
@item
Like @code{\new}, the @code{\context} command also directs a music
so the texts can be properly aligned to its notes,
@example
-\new Lyrics \lyricsto "@b{tenor}" @var{lyrics}
+\new Lyrics \lyricsto "@b{tenor}" @var{lyrics}
@end example
@noindent
@code{\context}, it is usually applied to @context{Voice}
@example
-\applyOutput #@var{function} % apply to Voice
+\applyOutput #'@var{context} #@var{function} % apply to Voice
@end example
To have it interpreted at the @context{Score} or @context{Staff} level use
these forms
@example
-\context Score \applyOutput #@var{function}
-\context Staff \applyOutput #@var{function}
+\applyOutput #'Score #@var{function}
+\applyOutput #'Staff #@var{function}
@end example
@end itemize
@subsection Changing context properties on the fly
@cindex properties
-@cindex @code{\set}
+@funindex \set
@cindex changing properties
Each context can have different @emph{properties}, variables contained
For example,
@lilypond[quote,verbatim,relative=2,fragment]
-R1*2
+R1*2
\set Score.skipBars = ##t
R1*2
@end lilypond
have no effect.
@lilypond[quote,verbatim,relative=2,fragment]
-R1*2
+R1*2
\set skipBars = ##t
R1*2
@end lilypond
Contexts are hierarchical, so if a bigger context was specified, for
example @context{Staff}, then the change would also apply to all
@context{Voice}s in the current stave. The change is applied
-`on-the-fly', during the music, so that the setting only affects the
+@q{on-the-fly}, during the music, so that the setting only affects the
second group of eighth notes.
-@cindex @code{\unset}
+@funindex \unset
There is also an @code{\unset} command,
@example
specified for a bottom context, so the two statements
@example
-\set Voice.autoBeaming = ##t
-\set autoBeaming = ##t
-@end example
+\set Voice.autoBeaming = ##t
+\set autoBeaming = ##t
+@end example
@noindent
are equivalent.
Notation contexts (like @code{Score} and @code{Staff}) not only
store properties,
-they also contain plug-ins called ``engravers'' that create notation
+they also contain plug-ins called @q{engravers} that create notation
elements. For example, the @code{Voice} context contains a
@code{Note_head_engraver} and the @code{Staff} context contains a
@code{Key_signature_engraver}.
-For a full a description of each plug-in, see
+For a full a description of each plug-in, see
@ifhtml
@internalsref{Engravers}.
@end ifhtml
@ifhtml
@internalsref{Contexts}
@end ifhtml
-@ifnothtml
+@ifnothtml
Program reference @arrow Translation @arrow{} Context.
@end ifnothtml
lists the engravers used for that context.
starting a new context with @code{\new} or @code{\context}, and
modifying it,
-@cindex @code{\with}
+@funindex \with
@example
\new @var{context} \with @{
objects. The settings used for printing these objects are also stored by
context. By changing these settings, the appearance of objects can be
altered.
-
+
The syntax for this is
@example
Here @var{name} is the name of a graphical object, like @code{Stem} or
@code{NoteHead}, and @var{property} is an internal variable of the
-formatting system (`grob property' or `layout property'). The latter is a
+formatting system (@q{grob property} or @q{layout property}). The latter is a
symbol, so it must be quoted. The subsection @ref{Constructing a
-tweak} explains what to fill in for @var{name}, @var{property}, and
+tweak}, explains what to fill in for @var{name}, @var{property}, and
@var{value}. Here we only discuss the functionality of this command.
The command
@verbatim
-\override Staff.Stem #'thickness = #4.0
+\override Staff.Stem #'thickness = #4.0
@end verbatim
@noindent
@lilypond[quote,verbatim,relative=2,fragment]
c4
-\override Staff.Stem #'thickness = #4.0
+\override Staff.Stem #'thickness = #4.0
c4
c4
c4
all stems are thickened.
Analogous to @code{\set}, the @var{context} argument may be left out,
-causing it to default to @context{Voice}, and adding @code{\once} applies
-the change during one timestep only
+causing the default context @context{Voice} to be used. Adding
+@code{\once} applies the change during one timestep only.
@lilypond[quote,fragment,verbatim,relative=2]
c4
-\once \override Stem #'thickness = #4.0
+\once \override Stem #'thickness = #4.0
+c4
c4
-c4
@end lilypond
The @code{\override} must be done before the object is
\override Slur #'thickness = #3.0
c8[( c
\override Beam #'thickness = #0.6
-c8 c])
+c8 c])
@end lilypond
@noindent
\revert Staff.Stem #'thickness
@end example
-Some tweakable options are called ``subproperties'' and reside inside
+Some tweakable options are called @q{subproperties} and reside inside
properties. To tweak those, use commands of the form
@c leave this as a long long
@}
@end example
-Here @code{\Staff} takes the existing definition for context @context{Staff} from the
-identifier @code{\Staff}.
+The @code{\Staff} command brings in the existing definition of the
+staff context so that it can be modified.
The statements
@example
}}
\relative c'' {
- a4 d8 bes8 \new ImproVoice { c4^"ad lib" c
- c4 c^"undress" c_"while playing :)" c }
- a1
+ a4 d8 bes8 \new ImproVoice { c4^"ad lib" c
+ c4 c^"undress" c_"while playing :)" c }
+ a1
}
@end lilypond
@}
@end example
-In the following discussion, the example input shown should go on the
-@dots{} in the previous fragment.
+In the following discussion, the example input shown should go in place
+of the @dots{} in the previous fragment.
-First the context's name is defined. Instead of @context{Voice} it
-will be called @context{ImproVoice},
+First it is necessary to define a name for the new context:
@example
\name ImproVoice
\alias Voice
@end example
-The context will print notes, and instructive texts
+The context will print notes and instructive texts, so we need to add
+the engravers which provide this functionality,
@example
\consists Note_heads_engraver
\consists Text_engraver
@end example
-but only on the center line,
+but we only need this on the center line,
@example
\consists Pitch_squash_engraver
@}
@end example
-@cindex @code{\accepts}
+@funindex \accepts
Contexts form hierarchies. We want to hang the @context{ImproVoice}
under @context{Staff}, just like normal @code{Voice}s. Therefore, we
modify the @code{Staff} definition with the @code{\accepts}
@example
\context @{
\Staff
- \accepts ImproVoice
+ \accepts ImproVoice
@}
@end example
-@cindex @code{\denies}
+@funindex \denies
The opposite of @code{\accepts} is @code{\denies},
which is sometimes needed when reusing existing context definitions.
\relative c'' @{
a4 d8 bes8
\new ImproVoice @{
- c4^"ad lib" c
+ c4^"ad lib" c
c4 c^"undress"
c c_"while playing :)"
@}
a1
@}
@end example
-
-
+
+@node Aligning contexts
+@subsection Aligning contexts
+
+New contexts may be aligned above or below exisiting contexts. This
+could be useful in setting up a vocal staff (@ref{Vocal ensembles}) and
+in ossia,
+
+@cindex ossia
+@findex alignAboveContext
+@findex alignBelowContext
+
+@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 }
+ >>
+ }
+}
+@end lilypond
+
+
+@node Vertical grouping of grobs
+@subsection Vertical grouping of grobs
+
+The VerticalAlignment and VerticalAxisGroup grobs work together.
+VerticalAxisGroup groups together different grobs like Staff, Lyrics,
+etc. VerticalAlignment then vertically aligns the different grobs
+grouped together by VerticalAxisGroup. There is usually only one
+VerticalAlignment per score but every Staff, Lyrics, etc. has its own
+VerticalAxisGroup.
+
@node The \override command
-@section The \override command
+@section The @code{\override} command
In the previous section, we have already touched on a command that
changes layout details: the @code{\override} command. In this section,
-we will look in more detail at how to use the command in practice.
+we will look in more detail at how to use the command in practice. The
+general syntax of this command is:
+@example
+\override @var{context}.@var{layout_object} #'@var{layout_property} = #@var{value}
+@end example
+
+This will set the @var{layout_property} of the specified @var{layout_object},
+which is a member of the @var{context}, to the @var{value}.
@menu
* Constructing a tweak::
* Layout interfaces::
* Determining the grob property::
* Objects connected to the input::
+* Using Scheme code instead of \tweak::
+* \set versus \override::
* Difficult tweaks::
@end menu
@end example
@noindent
-This means that we must determine these bits of information:
+To construct this tweak we must determine these bits of information:
@itemize
@item the context: here @context{Voice}.
@item the layout object: here @code{Stem}.
@item the layout property: here @code{thickness}.
@item a sensible value: here @code{3.0}.
-@end itemize
+@end itemize
-Some tweakable options are called ``subproperties'' and reside inside
+Some tweakable options are called @q{subproperties} and reside inside
properties. To tweak those, use commands in the form
@example
@cindex internal documentation
@cindex finding graphical objects
-@cindex graphical object descriptions
+@cindex graphical object descriptions
@cindex tweaking
-@cindex @code{\override}
+@funindex \override
@cindex internal documentation
+For many properties, regardless of the data type of the property, setting the
+property to false ( @code{##f} ) will result in turning it off, causing
+Lilypond to ignore that property entirely. This is particularly useful for
+turning off grob properties which may otherwise be causing problems.
+
We demonstrate how to glean this information from the notation manual
and the program reference.
+
+
@node Navigating the program reference
@subsection Navigating the program reference
@quotation
Accepted by: @internalsref{Fingering_engraver},
-@end quotation
+@end quotation
@noindent
That link brings us to the documentation for the Engraver, the
manual.
@end ignore
+@ifnothtml
+The programmer's reference is available as an HTML document. It is
+highly recommended that you read it in HTML form, either online or
+by downloading the HTML documentation. This section will be much more
+difficult to understand if you are using the
+PDF manual.
+@end ifnothtml
+
Follow the link to @internalsref{Fingering}. At the top of the
page, you will see
@internalsref{New_fingering_engraver}.
@end quotation
-By clicking around in the program reference, we can follow the
-flow of information within the program, following links like this:
+By following related links inside the program reference, we can follow the
+flow of information within the program:
@itemize @bullet
@item @internalsref{Fingering}:
@internalsref{Fingering} objects are created by:
-@b{@internalsref{Fingering_engraver}}
+@internalsref{Fingering_engraver}
@item @internalsref{Fingering_engraver}:
-Music types accepted: @b{@internalsref{fingering-event}}
+Music types accepted: @internalsref{fingering-event}
@item @internalsref{fingering-event}:
Music event type @code{fingering-event} is in Music expressions named
-@b{@internalsref{FingerEvent}}
+@internalsref{FingerEvent}
@end itemize
This path goes against the flow of information in the program: it
chapter lists all the definitions used and all properties that may be
tuned.
-
+
@node Layout interfaces
@subsection Layout interfaces
@quotation
@code{padding} (dimension, in staff space):
-
+
@code{0.5}
@end quotation
@noindent
-which means that the number will be kept at a distance of at least 0.6
+which means that the number will be kept at a distance of at least 0.5
of the note head.
Clicking any of the links will take you to the page of the respective
object interface. Each interface has a number of properties. Some of
-them are not user-serviceable (``Internal properties''), but others
+them are not user-serviceable (@q{Internal properties}), but others
can be modified.
We have been talking of @emph{the} @code{Fingering} object, but actually it
does not amount to much. The initialization file (see
@ref{Default files})
-@file{scm/@/define@/-grobs@/.scm} shows the soul of the `object',
+@file{scm/@/define@/-grobs@/.scm} shows the soul of the @q{object},
@example
(Fingering
@node Determining the grob property
@subsection Determining the grob property
-Recall that we wanted to change the position of the @b{2} in
+Recall that we wanted to change the position of the @b{2} in
@lilypond[quote,fragment,relative=2,verbatim]
c-2
Since the @b{2} is vertically positioned next to its note, we have to
meddle with the interface associated with this positioning. This is
-done using @code{side-position-interface}. The page for this interface
+done using @code{side-position-interface}. The page for this interface
says
@quotation
@item padding
(dimension, in staff space)
-Add this much extra space between objects that are next to each other.
+Add this much extra space between objects that are next to each other.
@end table
@end quotation
the @internalsref{Fingering_engraver} plug-in says
@quotation
-Fingering_engraver is part of contexts: @dots{} @b{@internalsref{Voice}}
+Fingering_engraver is part of contexts: @dots{} @internalsref{Voice}
@end quotation
@node Objects connected to the input
@subsection Objects connected to the input
-@cindex @code{\tweak}
+@funindex \tweak
In some cases, it is possible to take a short-cut for tuning graphical
-objects. For objects that result directly from a piece of the input,
+objects. For objects that result directly from a piece of the input,
you can use the @code{\tweak} function, for example
@lilypond[relative=2,fragment,verbatim,ragged-right]
\tweak #'color #red d
g
\tweak #'duration-log #1 a
->4-\tweak #'padding #10 -.
+>4-\tweak #'padding #10 -.
@end lilypond
-As you can see, properties are set directly in the objects directly,
+As you can see, properties are set in the objects directly,
without mentioning the grob name or context where this should be
applied.
an @internalsref{event} from the input, for example
@itemize @bullet
-@item note heads, caused by chord-pitch (i.e., notes inside a chord).
-@item articulation signs, caused by articulation instructions.
+@item note heads, caused by chord-pitch (i.e., notes inside a chord)
+@item articulation signs, caused by articulation instructions
@end itemize
It notably does not work for stems and accidentals (these are caused
@end example
@noindent
-will not change color. See @ref{Displaying music expressions} for
+does not change color. See @ref{Displaying music expressions}, for
details.
+@node Using Scheme code instead of \tweak
+@subsection Using Scheme code instead of @code{\tweak}
+
+The main disadvantage of @code{\tweak} is its syntactical
+inflexibility. For example, the following produces a syntax error.
+
+@example
+F = \tweak #'font-size #-3 -\flageolet
+
+\relative c'' @{
+ c4^\F c4_\F
+@}
+@end example
+
+@noindent
+With other words, @code{\tweak} doesn't behave like an articulation
+regarding the syntax; in particular, it can't be attached with
+@samp{^} and @samp{_}.
+
+Using Scheme, this problem can be circumvented. The route to the
+result is given in @ref{Adding articulation to notes (example)},
+especially how to use @code{\displayMusic} as a helping guide.
+
+@example
+F = #(let ((m (make-music 'ArticulationEvent
+ 'articulation-type "flageolet")))
+ (set! (ly:music-property m 'tweaks)
+ (acons 'font-size -3
+ (ly:music-property m 'tweaks)))
+ m)
+
+\relative c'' @{
+ c4^\F c4_\F
+@}
+@end example
+
+@noindent
+Here, the @code{tweaks} properties of the flageolet object
+@samp{m} (created with @code{make-music}) are extracted with
+@code{ly:music-property}, a new key-value pair to change the
+font size is prepended to the property list with the
+@code{acons} Scheme function, and the result is finally
+written back with @code{set!}. The last element of the
+@code{let} block is the return value, @samp{m} itself.
+
+
+@node \set versus \override
+@subsection @code{\set} vs. @code{\override}
+
+We have seen two methods of changing properties: @code{\set} and
+@code{\override}. There are actually two different kinds of
+properties.
+
+Contexts can have properties, which are usually named in
+@code{studlyCaps}. They mostly control the translation from
+music to notatino, eg. @code{localKeySignature} (for determining
+whether to print accidentals), @code{measurePosition} (for
+determining when to print a barline). Context properties can
+change value over time while interpreting a piece of music;
+@code{measurePosition} is an obvious example of
+this. Context properties are modified with @code{\set}.
+
+There is a special type of context property: the element
+description. These properties are named in @code{StudlyCaps}
+(starting with capital letters). They contain the
+@q{default settings} for said graphical object as an
+association list. See @file{scm/@/define@/-grobs@/.scm}
+to see what kind of settings there are. Element descriptions
+may be modified with @code{\override}.
+
+@code{\override} is actually a shorthand;
+
+@example
+\override @var{context}.@var{name} #'@var{property} = #@var{value}
+@end example
+
+@noindent
+is more or less equivalent to
+
+@c leave this long line -gp
+@example
+\set @var{context}.@var{name} #'@var{property} = #(cons (cons '@var{property} @var{value}) <previous value of @var{context})
+@end example
+
+The value of @code{context} (the alist) is used to initalize
+the properties of individual grobs. Grobs also have
+properties, named in Scheme style, with
+@code{dashed-words}. The values of grob properties change
+during the formatting process: formatting basically amounts
+to computing properties using callback functions.
+
+@code{fontSize} is a special property: it is equivalent to
+entering @code{\override ... #'font-size} for all pertinent
+objects. Since this is a common change, the special
+property (modified with @code{\set}) was created.
+
+
@node Difficult tweaks
@subsection Difficult tweaks
-There are a few classes of difficult adjustments.
+There are a few classes of difficult adjustments.
@itemize @bullet
In the following example, we define a procedure
@code{my-callback}. This procedure
-
+
@itemize @bullet
@item
determines if we have been split across line breaks
@lilypond[quote,verbatim,ragged-right]
#(define (my-callback grob)
(let* (
- ; have we been split?
+ ; have we been split?
(orig (ly:grob-original grob))
; if yes, get the split pieces (our siblings)
(eq? (car (last-pair siblings)) grob))
(ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
-\relative c'' {
+\relative c'' {
\override Tie #'after-line-breaking =
#my-callback
c1 ~ \break c2 ~ c
@item Some objects cannot be changed with @code{\override} for
-technical reasons. Examples of those are @code{NonMusicalPaperColumn}
+technical reasons. Examples of those are @code{NonMusicalPaperColumn}
and @code{PaperColumn}. They can be changed with the
-@code{\outputProperty} function, which works similar to @code{\once
-\override}, but uses a different syntax,
+@code{\overrideProperty} function, which works similar to @code{\once
+\override}, but uses a different syntax.
-@example
-\outputProperty
+@example
+\overrideProperty
#"Score.NonMusicalPaperColumn" % Grob name
-#'line-break-system-details % Property name
+#'line-break-system-details % Property name
#'((next-padding . 20)) % Value
@end example
+Note, however, that @code{\override}, applied to
+@code{NoteMusicalPaperColumn} and @code{PaperColumn}, still works as
+expected within @code{\context} blocks.
+
@end itemize
projects / lilypond.git / blobdiff