version that you are working on. See TRANSLATION for details.
@end ignore
+@c \version "2.11.38"
+
@node Tweaking output
@chapter Tweaking output
above, and so they too all have properties associated with them,
such as their position, size, color, etc.
-Some layout objects are still more specialised. Phrasing slurs,
-crescendo hairpins, ottavo marks, and many other grobs are not
-localised in a single place -- they have a starting point, an
+Some layout objects are still more specialized. Phrasing slurs,
+crescendo hairpins, ottava marks, and many other grobs are not
+localized in a single place -- they have a starting point, an
ending point, and maybe other properties concerned with their
shape. Objects with an extended shape like these are called
@q{Spanners}.
@ref{Contexts and engravers}. Here for reference is a list
of the most common object and property types together with
the conventions for naming them and a couple of examples of
-some real names. We have used A to stand for any capitalised
+some real names. We have used A to stand for any capitalized
alphabetic character and aaa to stand for any number of
lower-case alphabetic characters. Other characters are used
verbatim.
As we shall see shortly, the properties of different types of
object are modified by different commands, so it is useful to
-be able to recognise the type of object from the names of its
+be able to recognize the type of object from the names of its
properties.
@c See issue 509
@lilypond[quote,ragged-right,verbatim,fragment,relative=1]
\times 2/3 { c8[ c c]}
-\once \override TupletNumber
+\once \override TupletNumber
#'text = #tuplet-number::calc-fraction-text
\times 2/3 {
c[ c]
@cindex Internals Reference
@menu
-* Properties of layout objects::
-* Properties found in interfaces::
-* Types of properties::
+* Properties of layout objects::
+* Properties found in interfaces::
+* Types of properties::
@end menu
@node Properties of layout objects
{
\time 6/8
{
- r4 b8 b[( g]) g |
- g[( e]) e d[( f]) a |
+ r4 b8 b[( g]) g |
+ g[( e]) e d[( f]) a |
a g
}
\addlyrics {
- The man who feels love's sweet e -- mo -- tion
+ The man who feels love's sweet e -- mo -- tion
}
}
@end lilypond
a g
}
\addlyrics {
- The man who feels love's sweet e -- mo -- tion
+ The man who feels love's sweet e -- mo -- tion
}
}
@end lilypond
r4 b8
% Increase thickness of immediately following slur only
\once \override Slur #'thickness = #5.0
- b[( g]) g |
- g[( e]) e d[( f]) a |
- a g
+ b[( g]) g |
+ g[( e]) e d[( f]) a |
+ a g
}
\addlyrics {
- The man who feels love's sweet e -- mo -- tion
+ The man who feels love's sweet e -- mo -- tion
}
}
@end lilypond
b[( g]) g |
% Increase thickness of immediately following slur only
\once \override Slur #'thickness = #5.0
- g[( e]) e d[( f]) a |
+ g[( e]) e d[( f]) a |
a g
}
\addlyrics {
- The man who feels love's sweet e -- mo -- tion
+ The man who feels love's sweet e -- mo -- tion
}
}
@end lilypond
% Increase thickness of all following slurs from 1.2 to 5.0
\override Slur #'thickness = #5.0
b[( g]) g |
- g[( e])
+ g[( e])
% Revert thickness of all following slurs to default of 1.2
\revert Slur #'thickness
- e d[( f]) a |
+ e d[( f]) a |
a g
}
\addlyrics {
- The man who feels love's sweet e -- mo -- tion
+ The man who feels love's sweet e -- mo -- tion
}
}
@end lilypond
@code{LyricText} then tell you the values for those two
properties which apply to @code{LyricText}. Other objects
which support @code{font-interface} will set these
-properties diferently when they are created.
+properties differently when they are created.
Let's see if we can now construct the @code{\override} command
to change the lyrics to italics. The object is @code{LyricText},
LilyPond. Some of them are the names of properties,
like @code{thickness} or @code{font-shape}, others are in
effect special values that can be given to properties, like
-@code{italic}. Note the distinction from arbitary
+@code{italic}. Note the distinction from arbitrary
text strings, which would appear as @code{"a text string"}.
Ok, so the @code{\override} command we need to print the lyrics
}
\addlyrics {
\override LyricText #'font-shape = #'italic
- The man who feels love's sweet e -- mo -- tion
+ The man who feels love's sweet e -- mo -- tion
}
}
@end lilypond
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 recognise them. So the command should be:
+the interpreter cannot recognize them. So the command should be:
@example
\override Lyrics . LyricText #'font-shape = #'italic
@tab @code{2.5}, @code{0.34}
@item Direction
@tab A valid direction constant or its numerical equivalent
- @tab @code{#LEFT}, @code{#CENTER}, @code{#UP},
+ @tab @code{LEFT}, @code{CENTER}, @code{UP},
@code{1}, @code{-1}
@item Integer
@tab A positive whole number
@node Appearance of objects
@section Appearance of objects
-Let us now put what we have learnt into practice with a few
+Let us now put what we have learned into practice with a few
examples which show how tweaks may be used to change the
appearance of the printed music.
requires is actually a list of values in internal units,
but, to avoid having to know what these are, several ways
are provided to specify colors. The first way is to use one
-of the @q{normal} colours listed in the first table in
+of the @q{normal} colors listed in the first table in
@ruser{List of colors}. To set the bar lines to white
we write:
<<
{ f c c }
\new Staff \with {
- alignAboveContext = "main"
+ alignAboveContext = "main"
}
{
\override Staff.Clef #'stencil = ##f
@noindent
where the extra pair of braces after the @code{\with} clause are
-required to ensure the enclosed overrrides and music are applied
+required to ensure the enclosed overrides and music are applied
to the ossia staff.
But what is the difference between modifying the staff context by
context is created, and remain in force as the @strong{default}
values for the duration of that context, whereas
@code{\set} or @code{\override} commands embedded in the
-music are dynamic -- they make changes synchronised with
+music are dynamic -- they make changes synchronized with
a particular point in the music. If changes are unset or
reverted using @code{\unset} or @code{\revert} they return to
their default values, which will be the ones set in the
<<
{ f c c }
\new Staff \with {
- alignAboveContext = "main"
+ alignAboveContext = "main"
% Don't print clefs in this staff
\override Clef #'stencil = ##f
% Don't print time signatures in this staff
<<
{ f c c }
\new Staff \with {
- alignAboveContext = "main"
+ alignAboveContext = "main"
\override Clef #'stencil = ##f
\override TimeSignature #'stencil = ##f
% Reduce all font sizes by ~24%
<<
{ f c c }
\new Staff \with {
- alignAboveContext = "main"
+ alignAboveContext = "main"
\override Clef #'stencil = ##f
\override TimeSignature #'stencil = ##f
fontSize = #-2
value of the @code{staff-space} property these are automatically
scaled down in length too. Note that this affects only the
vertical scale of the ossia -- the horizontal scale is determined
-by the layout of the main music in order to remain synchronised
+by the layout of the main music in order to remain synchronized
with it, so it is not affected by any of these changes in size.
Of course, if the scale of all the main music were changed in this
way then the horizontal spacing would be affected. This is
@section Placement of objects
@menu
-* Automatic behaviour::
+* Automatic behavior::
* Within-staff objects::
* Outside staff objects::
@end menu
-@node Automatic behaviour
-@subsection Automatic behaviour
+@node Automatic behavior
+@subsection Automatic behavior
There are some objects in musical notation that belong to
the staff and there are other objects that should be
tied to other objects that are so positioned. Collisions of
note heads, stems and accidentals in closely set chords are
normally avoided automatically. There are commands and
-overrides which can modify this automatic behaviour, as we
+overrides which can modify this automatic behavior, as we
shall shortly see.
Objects belonging outside the staff include things such as
placed closer to the staff.
In the following example all the markup texts have the same
-priority (since it is not explicity set). Note that @q{Text3}
+priority (since it is not explicitly set). Note that @q{Text3}
is automatically positioned close to the staff again, nestling
under @q{Text2}.
These commands are essential when writing polyphonic music to
permit interweaving melodic lines to be distinguished.
But occasionally it may be necessary to override this automatic
-behaviour. This can be done for whole sections of music or even
+behavior. This can be done for whole sections of music or even
for an individual note. The property which controls this
-behaviour is the @code{direction} property of each layout object.
+behavior is the @code{direction} property of each layout object.
We first explain what this does, and then introduce a number of
ready-made commands which avoid your having to code explicit
overrides for the more common modifications.
right or left when they point up or down. This is controlled
automatically when @code{direction} is set.
-The following example shows in bar 1 the default behaviour of
+The following example shows in bar 1 the default behavior of
stems,
with those on high notes pointing down and those on low notes
pointing up, followed by four notes with all stems forced down,
four notes with all stems forced up, and finally four notes
-reverted back to the default behaviour.
+reverted back to the default behavior.
@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
a4 g c a
Here is a table of the commonest. The meaning of each is stated
where it is not obvious.
-@multitable @columnfractions .2 .2 .2 .4
-@headitem Down/Left
+@multitable @columnfractions .2 .2 .25 .35
+@headitem Down/Left
@tab Up/Right
@tab Revert
@tab Effect
to the left (if @code{left} appears, or to the right
(if @code{right} appears). Conversely, if a location is not
listed, no fingering is placed there. LilyPond takes these
-contraints and works out the best placement for the fingering
+constraints and works out the best placement for the fingering
of the notes of the following chords. Note that @code{left} and
@code{right} are mutually exclusive -- fingering may be placed
only on one side or the other, not both.
control the vertical placement of individual objects, although
the results may not always be desirable. Suppose we would
like @qq{Text3} to be placed above @qq{Text4} in the example
-under Automatic behaviour, above (see @ref{Automatic behaviour}).
+under Automatic behavior, above (see @ref{Automatic behavior}).
All we need to do is to look up the priority of @code{TextScript}
in the IR or in the tables above, and increase the priority of
@qq{Text3} to a higher value:
By default, text produced by markup takes up no horizontal space
as far as laying out the music is concerned. The @code{\textLengthOn}
-command reverses this behaviour, causing the notes to be spaced
+command reverses this behavior, causing the notes to be spaced
out as far as is necessary to accommodate the text:
@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
c^"Text4"
@end lilypond
-The command to revert to the default behaviour is
+The command to revert to the default behavior is
@code{\textLengthOff}. Remember @code{\once} only works with
@code{\override}, @code{\set}, @code{\revert} or @code{unset},
so cannot be used with @code{\textLengthOn}.
% Turn off collision avoidance
\once \override TextScript #'outside-staff-priority = ##f
\textLengthOn % and turn on textLengthOn
-c,,2^"Long Text " % Spaces at end are honoured
+c,,2^"Long Text " % Spaces at end are honored
c''2
@end lilypond
other objects will be moved automatically if necessary to make
room and (b) the single override can apply to all instances of
the same type of object. Such properties include:
+
@itemize
@item
Instead of @code{padding}, the placement of groups of accidentals
is controlled by @code{left-padding} and @code{right-padding}.
These properties are to be found in the @code{AccidentalPlacement}
-object which, note, lives in the @strong{staff} context. Because
-accidentals are always positioned after and to the left of
-note heads only the @code{right-padding} property has any effect.
+object which, note, lives in the @strong{staff} context. In the
+type-setting process the note heads are type-set first and then
+the accidentals, if any, are added to the left of the note heads
+using the @code{right-padding} property to determine the separation
+from the note heads. So only the @code{right-padding} property of the
+@code{AccidentalPlacement} object has any effect on the placement
+of the accidentals.
The @code{staff-padding} property is closely related to the
@code{padding} property: @code{padding}
@code{self-alignment-X}
@cindex self-alignment-X property
-This property can be used to align the object to the left, to
+This property can be used to align the object to the left, to
the right, or to center it with respect to the parent object's
reference point. It may be used with all objects which support
the @code{self-alignment-interface}. In general these are objects
to the leftmost extent and the second is added to the rightmost
extent. Negative numbers move the edge to the left, positive to
the right, so to widen an object the first number must be negative,
-the second positive. Note that not all objects honour both
+the second positive. Note that not all objects honor both
numbers. For example, the @code{Accidental} object only takes
notice of the first (left edge) number.
@cindex force-hshift property
-Closely spaced notes in a chord, or notes occuring at the same
+Closely spaced notes in a chord, or notes occurring at the same
time in different voices, are arranged in two, occasionally more,
columns to prevent the note heads overlapping. These are called
note columns, and an object called @code{NoteColumn} is created
@end itemize
-Objects do not all have all of these properties in general.
-It is necessary to go to the IR to look up which properties
-are available for the object in question.
-
@item
Finally, when all else fails, objects may be manually repositioned
-relative to the staff center line verically, or by
+relative to the staff center line vertically, or by
displacing them by any distance to a new position. The
disadvantages are that the correct values for the repositioning
have to be worked out, often by trial and error, for every object
requested positions is selected from the list.
@end table
-Objects do not all have all of these properties in general.
+@end enumerate
+
+A particular object may not have all of these properties.
It is necessary to go to the IR to look up which properties
are available for the object in question.
-@end enumerate
-
Here is a list of the objects which are most likely to be
involved in collisions, together with the name of the object which
should be looked up in the IR in order to discover which properties
object
is handled in the @code{Score} context, property changes in the
@code{Voice} context will not be noticed. For more details, see
-@ruser{Constructing a tweak}.
+@ruser{Modifying properties}.
If the @code{padding} property of an object is increased when that
object is in a stack of objects being positioned according to
index in the Notation Reference does not mention merging,
but a search of the text for @q{merge} quickly leads us to
the overrides for merging differently headed and differently
-dotted notes in @ruser{Collision Resolution}. In our
+dotted notes in @ruser{Collision resolution}. In our
example we need to merge both types of note for the duration
of the polyphonic section in bar 3, so using the information
in the Notation Reference we add
The C is in voice two which has shift off, and the two D's are in
voices one and three, which have shift off and shift on,
respectively. So we have to shift the C a further level still
-using @code{\shiftOnn} to avoid it interferring with the two D's.
+using @code{\shiftOnn} to avoid it interfering with the two D's.
Applying these changes gives:
@lilypond[quote,verbatim,ragged-right]
@section Further tweaking
@menu
-* Other uses for tweaks::
-* Using variables for tweaks::
-* Other sources of information::
-* Avoiding tweaks with slower processing::
-* Advanced tweaks with Scheme::
+* Other uses for tweaks::
+* Using variables for tweaks::
+* Other sources of information::
+* Avoiding tweaks with slower processing::
+* Advanced tweaks with Scheme::
@end menu
@node Other uses for tweaks
@subsection Other uses for tweaks
-@itemize
-
@cindex transparent property, use of
@cindex objects, making invisible
@cindex removing objects
@cindex invisible objects
@cindex tying notes across voices
-@item
@subheading Tying notes across voices
The following example demonstrates how to connect notes in
>>
@end lilypond
-@item
@subheading Simulating a fermata
@cindex stencil property, use of
to simulate a fermata in the MIDI output we would not want the
metronome markings to appear in the printed output, and we would
not want it to influence the spacing between the two systems or
-the spacing of the notes on the staff. So setting its
-@code{stencil} property to @code{#f} would be the best way.
+the positions of adjacent annotations on the staff. So setting
+its @code{stencil} property to @code{#f} would be the best way.
We show here the effect of the two methods:
@lilypond[quote,verbatim,ragged-right]
\tempo 4=120
a4 a a
\once \override Score.MetronomeMark #'transparent = ##t
- % Invisible tempo marking to lengthen fermata note in MIDI
+ % Invisible tempo marking to lengthen fermata in MIDI
\tempo 4=80
a\fermata
- \once \override Score.MetronomeMark #'stencil = ##f
- % Invisible tempo marking to restore tempo in MIDI
+ % New tempo for next section
+ \tempo 4=100
+ a a a a
+ }
+ \layout { }
+ \midi { }
+}
+@end lilypond
+
+@lilypond[quote,verbatim,ragged-right]
+\score {
+ \relative c'' {
+ % Visible tempo marking
\tempo 4=120
+ a4 a a
+ \once \override Score.MetronomeMark #'stencil = ##f
+ % Invisible tempo marking to lengthen fermata in MIDI
+ \tempo 4=80
+ a\fermata
+ % New tempo for next section
+ \tempo 4=100
a a a a
}
\layout { }
@end lilypond
@noindent
-Both methods remove the metronome mark from the printed output,
-and both affect the MIDI timing as required, but the first
-(transparent) metronome mark still influences the note spacing
-while the second (with no stencil) does not.
-
-@end itemize
+Both methods remove the metronome mark which lengthens the fermata
+from the printed output, and both affect the MIDI timing as
+required, but the transparent metronome mark in the first line
+forces the following tempo indication too high while the
+second (with the stencil removed) does not.
@node Using variables for tweaks
@subsection Using variables for tweaks
The Internals Reference documentation contains a lot of information
about LilyPond, but even more information can be gathered by
-looking at the internal LilyPond files. To explore these, first
-find the directory appropriate to your system, as follows:
+looking at the internal LilyPond files. To explore these, you must
+first find the directory appropriate to your system. The location
+of this directory depends (a) on whether you obtained LilyPond
+by downloading a precompiled binary from lilypond.org
+or whether you installed it from a package manager (i.e.
+distributed with Linux, or installed under fink or cygwin) or
+compiled it from source, and (b) on which operating system it is
+being used:
+
+@strong{Downloaded from lilypond.org}
-@strong{Linux}
+@itemize @bullet
+@item Linux
Navigate to
-@file{@var{installdir}/lilypond/usr/share/lilypond/current/}
+@file{@var{INSTALLDIR}/lilypond/usr/share/lilypond/current/}
-@strong{OSX}
+@item MacOS X
Navigate to
-@file{@var{installdir}/LilyPond.app/Contents/Resources/share/lilypond/current/}
+@file{@var{INSTALLDIR}/LilyPond.app/Contents/Resources/share/lilypond/current/}
by either @code{cd}-ing into this directory from the
Terminal, or control-clicking on the LilyPond application and
selecting @q{Show Package Contents}.
-@strong{Windows}
+@item Windows
Using Windows Explorer, navigate to
-@file{@var{installdir}/LilyPond/usr/share/lilypond/current/}
+@file{@var{INSTALLDIR}/LilyPond/usr/share/lilypond/current/}
+
+@end itemize
+
+@strong{Installed from a package manager or compiled from source}
+
+Navigate to
+@file{@var{PREFIX}/share/lilypond/@var{X.Y.Z}/}, where
+@var{PREFIX} is set by your package manager or @code{configure}
+script, and @var{X.Y.Z} is the LilyPond version number.
+
+@smallspace
Within this directory the two interesting subdirectories are
@itemize
-@item @file{../ly/ } - contains files in LilyPond format
-@item @file{../scm/} - contains files in Scheme format
+@item @file{ly/} - contains files in LilyPond format
+@item @file{scm/} - contains files in Scheme format
@end itemize
-Let's begin by looking at some files in @file{../ly/}.
-Open @file{../ly/property-init.ly} in a text editor. The one
+Let's begin by looking at some files in @file{ly/}.
+Open @file{ly/property-init.ly} in a text editor. The one
you normally use for @code{.ly} files will be fine. This file
contains the definitions of all the standard LilyPond built-in
commands, such as @code{\stemUp} and @code{\slurDotted}. You will
head of your input file.
The following are the most useful files to be found in
-@file{../ly/}:
+@file{ly/}:
@multitable @columnfractions .4 .6
@headitem Filename
@tab Contents
-@item @file{../ly/engraver-init.ly}
+@item @file{ly/engraver-init.ly}
@tab Definitions of engraver Contexts
-@item @file{../ly/paper-defaults.ly}
+@item @file{ly/paper-defaults.ly}
@tab Specifications of paper-related defaults
-@item @file{../ly/performer-init.ly}
+@item @file{ly/performer-init.ly}
@tab Definitions of performer Contexts
-@item @file{../ly/property-init.ly}
+@item @file{ly/property-init.ly}
@tab Definitions of all common built-in commands
@end multitable
@multitable @columnfractions .4 .6
@headitem Filename
@tab Contents
-@item @file{../scm/auto-beam.scm}
+@item @file{scm/auto-beam.scm}
@tab Sub-beaming defaults
-@item @file{../scm/define-grobs.scm}
+@item @file{scm/define-grobs.scm}
@tab Default settings for grob properties
-@item @file{../scm/define-markup-commands.scm}
+@item @file{scm/define-markup-commands.scm}
@tab Specify all markup commands
-@item @file{../scm/midi.scm}
+@item @file{scm/midi.scm}
@tab Default settings for MIDI output
-@item @file{../scm/output-lib.scm}
+@item @file{scm/output-lib.scm}
@tab Settings that affect appearance of frets, colors,
accidentals, bar lines, etc
-@item @file{../scm/parser-clef.scm}
+@item @file{scm/parser-clef.scm}
@tab Definitions of supported clefs
-@item @file{../scm/script.scm}
+@item @file{scm/script.scm}
@tab Default settings for articulations
@end multitable
@node Avoiding tweaks with slower processing
@subsection Avoiding tweaks with slower processing
-LilyPond can perform extra checks while it processes files. These
+LilyPond can perform extra checks while it processes input files. These
checks will take extra time to perform, but fewer manual tweaks
may be required to obtain an acceptable result. If a text script
or part of the lyrics extends over the margins these checks will
g1 |
}
\addlyrics {
- Some -- where o -- ver the Rain -- bow way up high,
+ Some -- where o -- ver the Rain -- bow, way up high,
}
@end lilypond
-
-
projects / lilypond.git / blobdiff