The general syntax of this command is:
@example
-\override @var{Context}.@var{LayoutObject} #'@var{layout-property} =
-#@var{value}
+\override @var{Context}.@var{LayoutObject}.@var{layout-property} = #@var{value}
@end example
@noindent
layout object with the name @var{LayoutObject}, which is a member of
the @var{Context} context, to the value @var{value}.
-The @var{Context} can be omitted (and usually is) when the
+The @var{Context} may be omitted (and usually is) when the
required context is unambiguously implied and is one of lowest
level contexts, i.e., @code{Voice}, @code{ChordNames} or
@code{Lyrics}, and we shall omit it in many of the following
examples. We shall see later when it must be specified.
Later sections deal comprehensively with properties and their
-values, see @ref{Types of properties}. But in this section we shall
+values, see @ref{Types of properties}. But in this section we shall
use just a few simple properties and values which are easily
understood in order to illustrate the format and use of these
commands.
-For now, don't worry about the @code{#'}, which must precede the
-layout property, and the@tie{}@code{#}, which must precede the value.
-These must always be present in exactly this form. This is the
-most common command used in tweaking, and most of the rest of
-this chapter will be directed to presenting examples of how it is
-used. Here is a simple example to change the color of the
-note head:
+LilyPond's primary expressions are musical items like notes,
+durations, and markups. More basic expressions like numbers,
+strings, and lists are processed in @q{Scheme mode}, which is
+invoked by prefixing the value with @samp{#}. Although the
+values may sometimes have a valid representation in LilyPond's
+musical mode, this manual will always use @samp{#} for their
+entry for the sake of consistency. For more information about
+Scheme mode, see @rextend{LilyPond Scheme syntax}.
+
+@code{\override} is the most common command used in tweaking, and
+most of the rest of this chapter will be directed to presenting
+examples of how it is used. Here is a simple example to change the
+color of the note head:
@cindex color property, example
@cindex NoteHead, example of overriding
commands have been issued.
@example
-\revert @var{Context}.@var{LayoutObject} #'@var{layout-property}
+\revert @var{Context}.@var{LayoutObject}.@var{layout-property}
@end example
Again, just like @var{Context} in the @code{\override} command,
of the @code{\tweak} command is
@example
-\tweak #'@var{layout-property} #@var{value}
+\tweak @var{layout-property} #@var{value}
@end example
A @code{\tweak} command can also be used to modify just one in
@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
<\tweak Accidental.color #red cis4
\tweak Accidental.color #green es
- g>
+ g>
@end lilypond
This long form of the @code{\tweak} command can be described as
+
@example
-\tweak @var{layout-object} #'@var{layout-property} @var{value}
+\tweak @var{layout-object}.@var{layout-property} @var{value}
@end example
@cindex tuplets, nested
@cindex transparent property, example
@cindex TupletNumber, example of overriding
-@c NOTE Tuplet brackets collide if notes are high on staff
-@c See issue 509
@lilypond[quote,ragged-right,verbatim,fragment,relative=1]
\times 2/3 { c8[ c c] }
\once \override TupletNumber.text = #tuplet-number::calc-fraction-text
\override Slur.thickness = #5.0
@end example
-Don't forget the @code{#'} preceding the
-property name and a@tie{}@code{#} preceding the new value!
+Don't forget the@tie{}@code{#} preceding the new value!
The final question is, @q{Where should this command be
placed?} While you are unsure and learning, the best
the property is @code{font-shape} and the value is
@code{italic}. As before, we'll omit the context.
-As an aside, although it is an important one, note that because the
-values of @code{font-shape} are symbols they must be introduced with a
-single apostrophe, @code{'}. That is why apostrophes are needed
-before @code{thickness} in the earlier example and @code{font-shape}.
-These are both symbols too. Symbols are then read internally by
-LilyPond. Some of them are the names of properties, like
-@code{thickness} or @code{font-shape}, others are used as values that
-can be given to properties, like @code{italic}. Note the distinction
-from arbitrary text strings, which would appear as @code{"a text
-string"}; for more details about symbols and strings, see
-@rextend{Scheme tutorial}.
+As an aside, although it is an important one, note that some
+properties take values that are symbols, like @code{italic}, and
+must be preceded by an apostrophe, @code{'}. Symbols are then
+read internally by LilyPond. Note the distinction from arbitrary
+text strings, which would appear as @code{"a text string"}; for
+more details about symbols and strings, see @rextend{Scheme tutorial}.
So we see that the @code{\override} command needed to print the lyrics
in italics is:
@noindent
and the lyrics are all printed in italics.
-@subheading Specifying the context in lyric mode
-
-@cindex context, specifying in lyric mode
-@cindex lyric mode, specifying context
-
-In the case of lyrics, if you try specifying the context in the
-format given earlier the command will fail. A syllable
-entered in lyricmode is terminated by either a space,
-a newline or a digit. All other characters are included
-as part of the syllable. For this reason a space or newline
-must appear before the terminating @code{@}} to prevent it being
-included as part of the final syllable. Similarly,
-spaces must be inserted before and after the
-period or dot, @q{.}, separating the context name from the
-object name, as otherwise the two names are run together and
-the interpreter cannot recognize them. So the command should be:
-
-@example
-\override Lyrics.LyricText.font-shape = #'italic
-@end example
-
@warning{In lyrics always leave whitespace between the final
syllable and the terminating brace.}
-@warning{In overrides in lyrics always place spaces around
-the dot between the context name and the object name.}
-
@seealso
Extending: @rextend{Scheme tutorial}.
to see the settings for each grob description. Grob descriptions
are modified with @code{\override}.
-@code{\override} is actually a shorthand;
+The syntax for the @code{\override} command is
@example
-\override @var{context}.@var{GrobName} #'@var{property} = #@var{value}
+\override [@var{context}.]@var{GrobName}.@var{property} = #@var{value}
@end example
-@noindent
-is more or less equivalent to
-
-@c leave this long line -gp
-@example
-\set @var{context}.@var{GrobName} =
- #(cons (cons '@var{property} @var{value})
- <previous value of @var{context}.@var{GrobName}>)
-@end example
-
-The value of @code{context}.@code{GrobName} (the alist) is used to initialize
-the properties of individual grobs. Grobs 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.
-
For example, we can increase the thickness of a note stem by
overriding the @code{thickness} property of the @code{Stem}
object:
}
@end lilypond
+Some tweakable options are called @q{subproperties} and reside inside
+properties. To tweak those, use commands in the form
+
+@example
+\override Stem.details.beamed-lengths = #'(4 4 3)
+@end example
+
+or to modify the ends of spanners, use a form like these
+
+@example
+\override TextSpanner.bound-details.left.text = #"left text"
+\override TextSpanner.bound-details.right.text = #"right text"
+@end example
+
@funindex \revert
@cindex reverting overrides
@cindex overrides, reverting
-The effects of @code{\override} can be undone by @code{\revert}:
+The effects of @code{\override} can be undone by @code{\revert}.
+
+The syntax for the @code{\revert} command is
+
+@example
+\revert [@var{context}.]@var{GrobName}.@var{property}
+@end example
+
+For example,
@lilypond[quote,verbatim,relative=2]
c4
@item a sensible value: here @code{3.0}.
@end itemize
-Some tweakable options are called @q{subproperties} and reside inside
-properties. To tweak those, use commands in the form
-
-@example
-\override Stem.details.beamed-lengths = #'(4 4 3)
-@end example
-
@cindex internal documentation
@cindex finding graphical objects
@cindex graphical object descriptions
syntax:
@example
-\tweak @var{layout-object} #'@var{grob-property} @var{value}
+\tweak [@var{layout-object}.]@var{grob-property} @var{value}
@end example
Specifying @var{layout-object} is optional.
-But the main use of the @code{\tweak} command is to modify just
+The main use of the @code{\tweak} command is to modify just
one of a number of notation elements which start at the same musical
moment, like the notes of a chord, or tuplet brackets which start
at the same time.
@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:
+Such indirectly created layout objects can be tweaked using the form
+of the @code{\tweak} command in which the grob name is specified
+explicitly:
@lilypond[relative=2,verbatim,quote]
\tweak Stem.color #red
circumstances to avoid errors:
@itemize
+
@item Around every opening and closing curly bracket.
+
@item After every command or variable, i.e. every item that
begins with a @code{\} sign.
+
@item After every item that is to be interpreted as a Scheme
expression, i.e. every item that begins with a @code{#}@tie{}sign.
+
@item To separate all elements of a Scheme expression.
-@item In @code{lyricmode} to separate all the terms in both
-@code{\override} and @code{\set} commands. In particular, spaces
-must be used around the dot and the equals sign in commands like
-@code{\override Score.LyricText.font-size = #5} and before and
-after the entire command.
+
+@item In @code{lyricmode} before and after @code{\set} and
+@code{\override} commands.
@end itemize
@end example
it will hold the current @code{\layout} configuration with the
-@code{NoteHead #'font-size} override added, but this combination
+@code{NoteHead.font-size} override added, but this combination
is @emph{not} saved as the new current configuration. Be aware
that the @q{current configuration} is read when the variable is
defined and not when it is used, so the content of the variable
consist of:
@example
- TextScript #'padding = #1
- TextScript #'color = #magenta
- Glissando #'thickness = #1.5
- NoteHead #' font-size = #4
- NoteHead #' color = #red
+ TextScript.padding = #1
+ TextScript.color = #magenta
+ Glissando.thickness = #1.5
+ NoteHead.font-size = #4
+ NoteHead.color = #red
@end example
plus the @code{indent} and the @code{StaffGrouper} overrides.
only
@example
- NoteHead #' font-size= #4 % (written in the variable definition)
- NoteHead #' color = #red % (added after the use of the variable)
+ NoteHead.font-size = #4 % (written in the variable definition)
+ NoteHead.color = #red % (added after the use of the variable)
@end example
If carefully planned, @code{\layout} variables can be a valuable tool
amount of vertical padding between staves and systems.
It is possible to approach vertical spacing in a different way
-using @code{NonMusicalPaperColumn #'line-break-system-details}.
+using @code{NonMusicalPaperColumn.line-break-system-details}.
While the flexible vertical spacing mechanisms specify vertical
-padding, @code{NonMusicalPaperColumn #'line-break-system-details}
+padding, @code{NonMusicalPaperColumn.line-break-system-details}
can specify exact vertical positions on the page.
-@code{NonMusicalPaperColumn #'line-break-system-details} accepts
+@code{NonMusicalPaperColumn.line-break-system-details} accepts
an associative list of three different settings:
@itemize
of the distance between adjacent staff lines. Positive values move staves
and lyrics up, negative values move staves and lyrics down.
-@item Because the @code{NonMusicalPaperColumn #'line-break-system-details}
+@item Because the @code{NonMusicalPaperColumn.line-break-system-details}
settings given here allow the positioning of staves and systems anywhere
on the page, it is possible to violate paper or margin boundaries or even
to print staves or systems on top of one another. Reasonable values
By default, spacing in tuplets depends on various non-duration
factors (such as accidentals, clef changes, etc). To disregard
such symbols and force uniform equal-duration spacing, use
-@code{Score.SpacingSpanner #'uniform-stretching}. This
+@code{Score.SpacingSpanner.uniform-stretching}. This
property can only be changed at the beginning of a score,
@lilypond[quote,ragged-right,verbatim]
\lyricmode @{ lah lah lah @}
@end example
-@cindex overrides in lyric mode
-@funindex \override in \lyricmode
-
-Similarly, in lyric mode, a period will be included in the
-alphabetic sequence that it follows. As a consequence, spaces
-must be inserted around the period in @code{\override} commands.
-Do @emph{not} write
-
-@example
-\override Score.LyricText.font-shape = #'italic
-@end example
-
-@noindent
-but instead use
-
-@example
-\override Score.LyricText.font-shape = #'italic
-@end example
-
Punctuation, lyrics with accented characters, characters from
non-English languages, or special characters (such as the heart
symbol or slanted quotes), may simply be inserted directly
projects / lilypond.git / commitdiff