manual. 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.5/@/Documentation/@/user/@/out@/-www/@/lilypond@/-internals/,on@/-line},
+@uref{http://@/lilypond@/.org/@/doc/@/v2.7/@/Documentation/@/user/@/lilypond@/-internals/,on@/-line},
but is also included with the LilyPond documentation package.
There are three areas where the default settings may be changed:
@menu
* Interpretation contexts::
* The \override command::
-* Fonts::
-* Text markup::
@end menu
staves. Each part that should be on its own staff, is preceded with
@code{\new Staff}.
-@lilypond[quote,verbatim,relative=2,raggedright,fragment]
+@lilypond[quote,verbatim,relative=2,ragged-right,fragment]
<< \new Staff { c4 c }
\new Staff { d4 d }
>>
setting lyrics the melody is in a named context
@example
-\CONtext Voice = "@b{tenor}" @var{music}
+\context Voice = "@b{tenor}" @var{music}
@end example
@noindent
\context Voice = "A" \arts
>>
@end example
-@lilypond[quote,raggedright]
+@lilypond[quote,ragged-right]
music = { c4 c4 }
arts = { s4-. s4-> }
\relative c'' <<
edition), with the option to put several distinct articulations on the
same notes.
-@cindex @code{\context}
@cindex creating contexts
The third command for creating contexts is
any context of type @var{type}, regardless of its given name.
This variant is used with music expressions that can be interpreted at
-several levels. For example, the @code{\applyoutput} command (see
+several levels. For example, the @code{\applyOutput} command (see
@ref{Running a function on all layout objects}). Without an explicit
@code{\context}, it is usually applied to @context{Voice}
@example
-\applyoutput #@var{function} % apply to Voice
+\applyOutput #@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}
+\context Score \applyOutput #@var{function}
+\context Staff \applyOutput #@var{function}
@end example
starting a new context, with @code{\new} or @code{\context}, and
modifying it like this,
+@cindex @code{\with}
+
@example
\new @var{context} \with @{
\consists @dots{}
The next example shows a practical application. Bar lines and time
signatures are normally synchronized across the score. This is done
-by the @code{Timing_engraver}. This plug-in keeps an administration of
-time signature, location within the measure, etc. By moving the
-@code{Timing_engraver} engraver from @code{Score} to @code{Staff}
-context, we can have a score where each staff has its own time
-signature.
+by the @code{Timing_translator} and @code{Default_bar_line_engraver}.
+This plug-in keeps an administration of time signature, location
+within the measure, etc. By moving thes engraver from @code{Score} to
+@code{Staff} context, we can have a score where each staff has its own
+time signature.
@cindex polymetric scores
@cindex Time signatures, multiple
-@lilypond[quote,relative=1,raggedright,verbatim,fragment]
+@lilypond[quote,relative=1,ragged-right,verbatim,fragment]
\new Score \with {
- \remove "Timing_engraver"
+ \remove "Timing_translator"
+ \remove "Default_bar_line_engraver"
} <<
\new Staff \with {
- \consists "Timing_engraver"
+ \consists "Timing_translator"
+ \consists "Default_bar_line_engraver"
} {
\time 3/4
c4 c c c c c
}
\new Staff \with {
- \consists "Timing_engraver"
+ \consists "Timing_translator"
+ \consists "Default_bar_line_engraver"
} {
\time 2/4
c4 c c c c c
\revert Staff.Stem #'thickness
@end example
+Some tweakable options are called ``subproperties'' and reside inside
+properties. To tweak those, use
+@example
+\override Stem #'details #'beamed-lengths = #'(4 4 3)
+@end example
@seealso
@code{Voice}, but prints centered slash noteheads only. It can be used
to indicate improvisation in Jazz pieces,
-@lilypond[quote,raggedright]
+@lilypond[quote,ragged-right]
\layout { \context {
\name ImproVoice
- \type "Engraver_group_engraver"
+ \type "Engraver_group"
\consists "Note_heads_engraver"
\consists "Text_engraver"
\consists Pitch_squash_engraver
All these plug-ins have to cooperate, and this is achieved with a
special plug-in, which must be marked with the keyword @code{\type}.
-This should always be @internalsref{Engraver_group_engraver},
+This should always be @internalsref{Engraver_group},
@example
-\type "Engraver_group_engraver"
+\type "Engraver_group"
@end example
Put together, we get
@example
\context @{
\name ImproVoice
- \type "Engraver_group_engraver"
+ \type "Engraver_group"
\consists "Note_heads_engraver"
\consists "Text_engraver"
\consists Pitch_squash_engraver
* Navigating the program reference::
* Layout interfaces::
* Determining the grob property::
+* Objects connected to the input::
* Difficult tweaks::
@end menu
The @code{padding} property for objects with
@cindex @code{padding}
@code{side-position-interface} can be set to increase the distance between
-symbols that are printed above or below notes. We only give an
-example; a more elaborate explanation is in @ref{Constructing a
+symbols that are printed above or below notes. We provide two
+examples; a more elaborate explanation is in @ref{Constructing a
tweak}:
@lilypond[quote,fragment,relative=1,verbatim]
b2\fermata
@end lilypond
+@lilypond[quote,fragment,relative=1,verbatim]
+% This will not work, see below:
+\override MetronomeMark #'padding = #3
+\tempo 4=120
+c1
+% This works:
+\override Score.MetronomeMark #'padding = #3
+\tempo 4=80
+d1
+@end lilypond
+
+Note in the second example how important it is to figure out what
+context handles a certain object. Since the @code{MetronomeMark} object
+is handled in the Score context, property changes in the @code{Voice}
+context will not be noticed.
+
@end itemize
+Some tweakable options are called ``subproperties'' and reside inside
+properties. To tweak those, use
+
+@example
+\override Stem #'details #'beamed-lengths = #'(4 4 3)
+@end example
+
+@cindex Tweaks, distances
+@cindex Distances
+
+Distances in LilyPond are measured in staff-spaces, while most
+thickness properties are measured in line-thickness. Some
+properties are different; for example, the thickness of beams
+is measured in staff-spaces. For more information, see the
+relevant portion of the program reference.
+
More specific overrides are also possible. The next section
discusses in depth how to figure out these statements for yourself.
In other words, once the @code{FingerEvent}s are interpreted, the
@code{Fingering_engraver} plug-in will process them.
+
+@ignore
+@c I can't figure out what this is supposed to mean. -gp
+
The @code{Fingering_engraver} is also listed to create
@internalsref{Fingering} objects,
-
-Lo and behold, that is also the
+@c old info? it doesn't make any sense to me with our current docs.
+This is also the
second bit of information listed under @b{See also} in the Notation
-manual. By clicking around in the program reference, we can follow the
+manual.
+@end ignore
+
+By clicking around in the program reference, we can follow the
flow of information within the program, either forward (like we did
here), or backwards, following links like this:
@cindex interface, layout
@cindex layout interface
+@cindex grob
The HTML page that we found in the previous section, describes the
layout object called @internalsref{Fingering}. Such an object is a
symbol within the score. It has properties that store numbers (like
thicknesses and directions), but also pointers to related objects. A
-layout object is also called @emph{grob},
-@cindex grob
-which is short for Graphical Object.
-
+layout object is also called a @emph{Grob}, which is short for Graphical
+Object. For more details about Grobs, see @internalsref{grob-interface}.
The page for @code{Fingering} lists the definitions for the
@code{Fingering} object. For example, the page says
@example
(Fingering
- . ((print-function . ,Text_interface::print)
- (padding . 0.6)
- (staff-padding . 0.6)
+ . ((padding . 0.5)
+ (avoid-slur . around)
+ (slur-padding . 0.2)
+ (staff-padding . 0.5)
(self-alignment-X . 0)
(self-alignment-Y . 0)
(script-priority . 100)
- (font-size . -5)
- (meta . ((interfaces . (finger-interface font-interface
- text-script-interface text-interface
- side-position-interface
- self-alignment-interface
- item-interface))))))
+ (stencil . ,ly:text-interface::print)
+ (direction . ,ly:script-interface::calc-direction)
+ (font-encoding . fetaNumber)
+ (font-size . -5) ; don't overlap when next to heads.
+ (meta . ((class . Item)
+ (interfaces . (finger-interface
+ font-interface
+ text-script-interface
+ text-interface
+ side-position-interface
+ self-alignment-interface
+ item-interface))))))
@end example
@noindent
Fingering_engraver is part of contexts: @dots{} @b{@internalsref{Voice}}
@end quotation
-@node Difficult tweaks
-@subsection Difficult tweaks
+@node Objects connected to the input
+@subsection Objects connected to the input
+
+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,
+you can use the @code{\tweak} function, for example
-There are two classes of difficult adjustments. First, when there are
-several of the same objects at one point, and you want to adjust only
-one. For example, if you want to change only one note head in a chord.
+@lilypond[relative=2,fragment,verbatim,ragged-right]
+<
+ c
+ \tweak #'color #red d
+ g
+ \tweak #'duration-log #1 a
+>4-\tweak #'padding #10 -.
+@end lilypond
-In this case, the @code{\applyoutput} function must be used. The
-next example defines a Scheme function @code{set-position-font-size}
-that sets the @code{font-size} property, but only
-on objects that have @internalsref{note-head-interface} and are at the
-right Y-position.
+As you can see, properties are set directly in the objects directly,
+without mentioning the grob name or context where this should be
+applied.
-@lilypond[quote,verbatim]
-#(define ((set-position-font-size pos size) grob origin current)
- (let*
- ((interfaces (ly:grob-property grob 'interfaces))
- (position (ly:grob-property grob 'staff-position)))
- (if (and
- ; is this a note head?
- (memq 'note-head-interface interfaces)
+This technique only works for objects that are directly connected to
+an @internalsref{event} from the input, for example
- ; is the Y coordinate right?
- (= pos position))
+@itemize @bullet
+@item note heads, caused by chord-pitch.
+@item articulation signs, caused by articulation instructions
+@end itemize
- ; then do it.
- (set! (ly:grob-property grob 'font-size) size))))
+It notably does not work for stems and accidentals (these are caused
+by note heads, not by music events) or clefs (these are not caused by
+music inputs, but rather by the change of a property value).
+
+In a similar vein, objects may be parenthesized by prefixing
+@code{\parenthesize} to the music event,
-\relative {
+@lilypond[relative=2,fragment,verbatim,ragged-right]
+<
c
- \applyoutput #(set-position-font-size -2 4)
- <c e g>
-}
+ \parenthesize d
+ g
+>4-\parenthesize -.
@end lilypond
-@noindent
-A similar technique can be used for accidentals. In that case, the
-function should check for @code{accidental-interface}.
-Another difficult adjustment is the appearance of spanner objects,
+
+
+@node Difficult tweaks
+@subsection Difficult tweaks
+
+There are a few classes of difficult adjustments.
+
+@itemize @bullet
+
+
+@item
+One type of difficult adjustment is the appearance of spanner objects,
such as slur and tie. Initially, only one of these objects is created,
and they can be adjusted with the normal mechanism. However, in some
cases the spanners cross line breaks. If this happens, these objects
in. These are clones of the original object and inherit all
properties, including @code{\override}s.
+
In other words, an @code{\override} always affects all pieces of a
broken spanner. To change only one part of a spanner at a line break,
it is necessary to hook into the formatting process. The
-@code{after-line-breaking-callback} property contains the Scheme procedure
-that is called after the line breaks have been determined, and layout
+@code{after-line-breaking} callback contains the Scheme procedure that
+is called after the line breaks have been determined, and layout
objects have been split over different systems.
In the following example, we define a procedure
This procedure is installed into @internalsref{Tie}, so the last part
of the broken tie is translated up.
-
-@lilypond[quote,verbatim,raggedright]
+@lilypond[quote,verbatim,ragged-right]
#(define (my-callback grob)
(let* (
; have we been split?
(ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
\relative c'' {
- \override Tie #'after-line-breaking-callback =
+ \override Tie #'after-line-breaking =
#my-callback
c1 ~ \break c2 ~ c
}
@end lilypond
@noindent
-When applying this trick, the new @code{after-line-breaking-callback}
-should also call the old @code{after-line-breaking-callback}, if there
-is one. For example, if using this with @code{Slur},
-@code{Slur::after_line_breaking} should also be called.
-
-@node Fonts
-@section Fonts
-
-This section details the ways that the font can be changed.
-
-@menu
-* Selecting font sizes::
-* Font selection::
-@end menu
-
-
-
-@node Selecting font sizes
-@subsection Selecting font sizes
-
-
-The easiest method of setting the font size of any context, is by
-setting the @code{fontSize} property.
-
-@lilypond[quote,fragment,relative=1,verbatim]
-c8
-\set fontSize = #-4
-c f
-\set fontSize = #3
-g
-@end lilypond
-
-@noindent
-It does not change the size of variable symbols, such as beams or
-slurs.
-
-Internally, the @code{fontSize} context property will cause the
-@code{font-size} property to be set in all layout objects. The value
-of @code{font-size} is a number indicating the size relative to the
-standard size for the current staff height. Each step up is an
-increase of approximately 12% of the font size. Six steps is exactly a
-factor two. The Scheme function @code{magstep} converts a
-@code{font-size} number to a scaling factor.
-
-@lilypond[quote,fragment,relative=1,verbatim]
-c8
-\override NoteHead #'font-size = #-4
-c f
-\override NoteHead #'font-size = #3
-g
-@end lilypond
-
-LilyPond has fonts in different design sizes. The music fonts for
-smaller sizes are chubbier, while the text fonts are relatively wider.
-Font size changes are achieved by scaling the design size that is
-closest to the desired size. The standard font size (for
-@code{font-size} equals 0), depends on the standard staff height. For
-a 20pt staff, a 10pt font is selected.
-
-The @code{font-size} property can only be set on layout objects that
-use fonts. These are the ones supporting the
-@internalsref{font-interface} layout interface.
-
-@refcommands
-
-The following commands set @code{fontSize} for the current voice:
-
-@cindex @code{\tiny}
-@code{\tiny},
-@cindex @code{\small}
-@code{\small},
-@cindex @code{\normalsize}
-@code{\normalsize}.
-
-
-
-@cindex magnification
-@cindex cue notes
-
-
-@node Font selection
-@subsection Font selection
-
-
-
-@cindex font selection
-@cindex font magnification
-@cindex @code{font-interface}
-
-By setting the object properties described below, you can select a
-font from the preconfigured font families. LilyPond has default
-support for the feta music fonts and @TeX{}'s Computer Modern text
-fonts.
-
-
-@itemize @bullet
-@item @code{font-encoding}
-is a symbol that sets layout of the glyphs. This should only be set to
-select different types of non-text fonts, eg.
-
-@code{fetaBraces} for piano staff braces, @code{fetaMusic} the
-standard music font, including ancient glyphs, @code{fetaDynamic} for
-dynamic signs and @code{fetaNumber} for the number font.
-
-@item @code{font-family}
-is a symbol indicating the general class of the typeface. Supported are
-@code{roman} (Computer Modern), @code{sans}, and @code{typewriter}.
-
-@item @code{font-shape}
-is a symbol indicating the shape of the font. There are typically
-several font shapes available for each font family. Choices are
-@code{italic}, @code{caps}, and @code{upright}.
-
-@item @code{font-series}
-is a symbol indicating the series of the font. There are typically
-several font series for each font family and shape. Choices are
-@code{medium} and @code{bold}.
-
-@end itemize
-
-Fonts selected in the way sketched above come from a predefined style
-sheet. If you want to use a font from outside the style sheet,
-then set the
-@code{font-name} property,
-
-@lilypond[fragment,verbatim]
-{
- \override Staff.TimeSignature #'font-name = #"Times"
- \override Staff.TimeSignature #'font-size = #2
- \time 3/4
- c'1_\markup {
- \override #'(font-name . "Vera Bold")
- { This text is in Vera Bold }
- }
-}
-@end lilypond
-
-@noindent
-Any font can be used, as long as it is available to Pango/FontConfig.
-
-The size of the font may be set with the @code{font-size}
-property. The resulting size is taken relative to the
-@code{text-font-size} as defined in the @code{\paper} block.
-
-
-@cindex font size
-@cindex font magnification
-
-
-
-@seealso
-
-Init files: @file{ly/@/declarations@/-init@/.ly} contains hints how new
-fonts may be added to LilyPond.
-
-
-
-@node Text markup
-@section Text markup
-@cindex text markup
-@cindex markup text
-
-
-@cindex typeset text
-
-The internal mechanism to typeset texts is accessed with the keyword
-@code{\markup}. Within markup mode, you can enter texts similar to
-lyrics. They are simply entered, while commands use the backslash @code{\}.
-@cindex markup
-
-@lilypond[quote,verbatim,fragment,relative=1]
-c1^\markup { hello }
-c1_\markup { hi there }
-c1^\markup { hi \bold there, is \italic anyone home? }
-@end lilypond
-
-@cindex font switching
-
-The markup in the example demonstrates font switching commands. The
-command @code{\bold} and @code{\italic} apply to the first following
-word only; enclose a set of texts with braces to apply a command
-to more words:
-@example
-\markup @{ \bold @{ hi there @} @}
-@end example
-
-@noindent
-For clarity, you can also do this for single arguments, e.g.,
-
-@example
-\markup @{ is \italic @{ anyone @} home @}
-@end example
-
-@cindex font size, texts
-
-
-In markup mode you can compose expressions, similar to mathematical
-expressions, XML documents, and music expressions. You can stack
-expressions grouped vertically with the command @code{\column}.
-Similarly, @code{\center-align} aligns texts by their center lines:
-
-@lilypond[quote,verbatim,fragment,relative=1]
-c1^\markup { \column { a bbbb \line { c d } } }
-c1^\markup { \center-align { a bbbb c } }
-c1^\markup { \line { a b c } }
-@end lilypond
-
-
-Markups can be stored in variables and these variables
-may be attached to notes, like
-@example
-allegro = \markup @{ \bold \large @{ Allegro @} @}
- @{ a^\allegro b c d @}
-@end example
-
-
-Some objects have alignment procedures of their own, which cancel out
-any effects of alignments applied to their markup arguments as a
-whole. For example, the @internalsref{RehearsalMark} is horizontally
-centered, so using @code{\mark \markup @{ \left-align .. @}} has no
-effect.
-
-Similarly, for moving whole texts over notes with
-@code{\raise}, use the following trick:
-@lilypond[quote,verbatim]
-{
- c'^\markup { \raise #0.5 not-raised }
- c'^\markup { "" \raise #0.5 raised }
-}
-@end lilypond
-
-On the second note, the text @code{raised} is moved relative to the
-empty string @code{""} which is not visible. Alternatively, complete
-objects can be moved with layout properties such as @code{padding} and
-@code{extra-offset}.
-
-
-
-
-@seealso
-
-Init files: @file{scm/@/new@/-markup@/.scm}.
-
-
-@refbugs
-
-Kerning or generation of ligatures is only done when the @TeX{}
-backend is used. In this case, LilyPond does not account for them so
-texts will be spaced slightly too wide.
-
-Syntax errors for markup mode are confusing.
-
-
-@menu
-* Text encoding::
-* Nested scores::
-* Overview of text markup commands::
-* New dynamic marks::
-* Other text markup issues::
-@end menu
-
-@node Text encoding
-@subsection Text encoding
-
-LilyPond uses the Pango library to format multi-lingual texts, and
-does not perform any input-encoding conversions. This means that any
-text, be it title, lyric text, or musical instruction containing
-non-ASCII characters, must be utf-8. Easiest to enter such texts is
-by using a Unicode-aware editor, and save using utf-8 encoding. Most
-popular modern editors have utf-8 support, for example, vim, Emacs,
-jEdit, and GEdit do.
-
-Depending on the fonts installed, the following fragment shows Hebrew
-and Cyrillic lyrics,
-
-@cindex Cyrillic
-@cindex Hebrew
-@cindex ASCII, non
-
-@lilypondfile[fontload]{utf-8.ly}
-
-
-The @TeX{} backend does not handle encoding specially at all. Strings
-in the input are put in the output as-is. Extents of text items in the
-@TeX{} backend, are determined by reading a file created via the
-@file{texstr} backend,
-
-@example
-lilypond -b texstr input/les-nereides.ly
-latex les-nereides.texstr
+When applying this trick, the new @code{after-line-breaking} callback
+should also call the old one @code{after-line-breaking}, if there is
+one. For example, if using this with @code{Hairpin},
+@code{ly:hairpin::after-line-breaking} should also be called.
+
+
+@item Some objects cannot be changed with @code{\override} for
+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,
+
+@example
+\outputProperty
+#"Score.NonMusicalPaperColumn" % Grob name
+#'line-break-system-details % Property name
+#'((next-padding . 20)) % Value
@end example
-The last command produces @file{les-nereides.textmetrics}, which is
-read when you execute
-
-@example
-lilypond -b tex input/les-nereides.ly
-@end example
-
-Both @file{les-nereides.texstr} and @file{les-nereides.tex} need
-suitable LaTeX wrappers to load appropriate La@TeX{} packages for
-interpreting non-ASCII strings.
-
-@seealso
-
-@inputfileref{input/regression,utf-8.ly}
-
-
-@node Nested scores
-@subsection Nested scores
-
-It is possible to nest music inside markups, by adding a @code{\score}
-block to a markup expression. Such a score must contain a @code{\layout}
-block.
-
-@lilypond[quote,verbatim,raggedright]
-\relative {
- c4 d^\markup {
- \score {
- \relative { c4 d e f }
- \layout { }
- }
- }
- e f
-}
-@end lilypond
-
-
-
-@node Overview of text markup commands
-@subsection Overview of text markup commands
-
-The following commands can all be used inside @code{\markup @{ @}}.
-
-@include markup-commands.tely
-
-
-@node New dynamic marks
-@subsection New dynamic marks
-
-It is possible to print new dynamic marks or text that should be aligned
-with dynamics. Use @code{make-dynamic-script} to create these marks.
-
-@cindex make-dynamic-script
-
-@lilypond[quote,verbatim,raggedright]
-sfzp = #(make-dynamic-script "sfzp")
-\relative c' {
- c4 c c\sfzp c
-}
-@end lilypond
-
-@cindex Dynamics, editorial
-@cindex Dynamics, parenthesis
-
-It is also possible to print dynamics in round parenthesis or square
-brackets. These are often used for adding editorial dynamics.
-
-@lilypond[quote,verbatim,raggedright]
-\version "2.4.2"
-rndf = \markup{ \center-align {\line { \bold{\italic (}
- \dynamic f \bold{\italic )} }} }
-boxf = \markup{ \bracket { \dynamic f } }
-{ c'1_\rndf c'1_\boxf }
-@end lilypond
-
-
-@node Other text markup issues
-@subsection Other text markup issues
-
-To use a normal font within a title, you must define it manually
-
-@example
-#(def-markup-command (normal-font layout props arg) (markup?)
- "Switch to normal text font"
- (interpret-markup layout (cons '((font-series . 'medium) (font-shape . 'upright)) props) arg))
-
-\header@{
- title = \markup@{ ABCD \normal-font ABCD @}
-@}
-@end example
-
-
-
+@end itemize
projects / lilypond.git / blobdiff