version that you are working on. See TRANSLATION for details.
@end ignore
+@c \version "2.11.38"
+
@node Changing defaults
@chapter Changing defaults
@item
Page layout: changing the appearance of the spacing, line
breaks, and page dimensions. These modifications are discussed
-in @ref{Non-musical notation}, and @ref{Spacing issues}.
+@c in @ref{notation}, and @ref{Spacing issues}.
@end itemize
Internally, LilyPond uses Scheme (a LISP dialect) to provide
@menu
-* Interpretation contexts::
-* The \override command::
+* Interpretation contexts::
+* Explaining the Internals Reference::
+* Modifying properties::
+* Useful concepts and properties::
+* Common properties::
+* Advanced tweaks::
+* old The \override command::
+* Discussion of specific tweaks::
@end menu
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::
+* Contexts explained::
+* Creating contexts::
+* Modifying context plug-ins::
+* Changing context default settings::
+* Defining new contexts::
+* Aligning contexts::
@end menu
@node Contexts explained
@subsection Contexts explained
-When music is printed, a lot of notational elements must be added to the
-output. For example, compare the input and output of the following example:
-
-@lilypond[quote,verbatim,relative=2,fragment]
-cis4 cis2. g4
-@end lilypond
-
-The input is rather sparse, but in the output, bar lines, accidentals,
-clef, and time signature are added. LilyPond @emph{interprets} the
-input. During this step, the musical information is inspected in time
-order, similar to reading a score from left to right. While reading
-the input, the program remembers where measure boundaries are, and which
-pitches require explicit accidentals. This information can be presented on
-several levels. For example, the effect of an accidental is limited
-to a single staff, while a bar line must be synchronized across the
-entire score.
-
-Within LilyPond, these rules and bits of information are grouped in
-@emph{Contexts}. Some examples of contexts are @context{Voice},
-@context{Staff}, and @context{Score}. They are hierarchical, for
-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
-accidental and then the @context{Staff} context maintains the rule to
-show or suppress the accidental for the remainder of the measure. The
-synchronization of bar lines is handled at @context{Score} context.
-
-However, in some music we may not want the bar lines to be
-synchronized -- consider a polymetric score in 4/4 and 3/4 time. In
-such cases, we must modify the default settings of the @context{Score}
-and @context{Staff} contexts.
-
-For very simple scores, contexts are created implicitly, and you need
-not be aware of them. For larger pieces, such as anything with more
-than one staff, they must be
-created explicitly to make sure that you get as many staves as you
-need, and that they are in the correct order. For typesetting pieces
-with specialized notation, it can be useful to modify existing or
-to define new contexts.
-
-
-A complete description of all available contexts is in the program
-reference, see
-@ifhtml
-@internalsref{Contexts}.
-@end ifhtml
-@ifnothtml
-Translation @expansion{} Context.
-@end ifnothtml
+>> > > - list of contexts: my *danger unmaintainable*
+>> > > alarm just went off. I'm
+
+I knew it would... And leaving out some of them is perfectly fine
+with me.
+I do think that a list like this, with the main contexts and a
+brief
+description of what they do (perhaps also with a note about what
+default
+behavior is associated with each of them, but this may be
+unmanageable),
+should be there, and then we could simply list the remaining ones
+without
+further explanation and with links to the IR.
+
+
+The Master Of All Contexts
+==========================
+
+ * Score
+ This is the top level notation context. No other context
+can
+ contain a Score context. This context handles the
+ administration of time signatures. It also makes sure that
+ items such as clefs, time signatures, and key-signatures
+are
+ aligned across staves.
+ You cannot explicitly instantiate a Score context (since
+it is
+ not contained in any other context). It is instantiated
+ automatically when an output definition (a \score or
+\layout
+ block) is processed.
+ (it should also be made clear somewhere what the
+difference is between
+ \score and \Score).
+
+Top-level contexts: Staff containers
+====================================
+ * StaffGroup
+ Groups staves while adding a bracket on the left side,
+ grouping the staves together. The bar lines of the
+contained
+ staves are connected vertically. StaffGroup only consists
+of a
+ collection of staves, with a bracket in front and spanning
+bar
+ lines.
+ * ChoirStaff
+ Identical to StaffGroup except that the contained staves
+are
+ not connected vertically.
+ * GrandStaff
+ A group of staves, with a brace on the left side, grouping
+the
+ staves together. The bar lines of the contained staves are
+ connected vertically.
+ * PianoStaff
+ Just like GrandStaff but with a forced distance between
+the
+ staves, so cross staff beaming and slurring can be used.
+ * DrumStaff
+ Handles typesetting for percussion. Can contain DrumVoice
+ * InnerStaffGroup
+ * InnerChoirStaff
+
+Staff-level contexts
+====================
+ * Staff
+ Handles clefs, bar lines, keys, accidentals. It can
+contain
+ Voice contexts.
+ * RhythmicStaff
+ Like Staff but for printing rhythms. Pitches are
+ ignored; the notes are printed on one line.
+ * TabStaff
+ Context for generating tablature. By default lays the
+music
+ expression out as a guitar tablature, printed on six
+lines.
+ * VaticanaStaff
+ Same as Staff, except that it is accommodated for
+ typesetting a piece in gregorian style.
+ * MensuralStaff
+ Same as Staff, except that it is accommodated for
+ typesetting a piece in mensural style.
+
+Voice-level (bottom) contexts
+=============================
+What is generated by default here? The voice-level contexts
+initiate
+certain properties and start engravers.
+
+ * Voice
+ Corresponds to a voice on a staff. This context handles
+the
+ conversion of dynamic signs, stems, beams, super- and
+ subscripts, slurs, ties, and rests.
+ You have to instantiate this explicitly if you want to
+have
+ multiple voices on the same staff.
+ Bottom context.
+ * VaticanaVoice
+ Same as Voice, except that it is accommodated for
+ typesetting a piece in gregorian style.
+ * MensuralVoice
+ Same as Voice, except that it is accommodated for
+ typesetting a piece in mensural style.
+ * Lyrics
+ Corresponds to a voice with lyrics. Handles the printing
+of a
+ single line of lyrics.
+ Bottom context.
+ * DrumVoice
+ A voice on a percussion staff.
+ * FiguredBass
+
+ * ChordNames
+ Typesets chord names. This context is a `bottom' context;
+it
+ cannot contain other contexts.
+
+------------------------------
+Then the following, which I don't know what to do with:
+
+ * TabVoice
+ * GregorianTranscriptionVoice
+ * GregorianTranscriptionStaff
+
+ * FretBoards
+ Engraves fretboards from chords. Not easy... Not
+documented.
+ * NoteNames
+
+ * CueVoice Not documented
+ * Global
+ Hard coded entry point for LilyPond. Cannot be tuned.
+ * Devnull
+ Silently discards all musical information given to this
+context.
-@c [TODO: describe propagation]
@node Creating contexts
arts = @{ s4-. s4-> @}
@end example
-They are combined by sending both to the same @context{Voice} context,
+They are combined by sending both to the same @code{Voice} context,
@example
<<
This variant is used with music expressions that can be interpreted at
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}
+@code{\context}, it is usually applied to @code{Voice}
@example
\applyOutput #'@var{context} #@var{function} % apply to Voice
@end example
-To have it interpreted at the @context{Score} or @context{Staff} level use
+To have it interpreted at the @code{Score} or @code{Staff} level use
these forms
@example
@end itemize
-@node Changing context properties on the fly
-@subsection Changing context properties on the fly
-
-@cindex properties
-@funindex \set
-@cindex changing properties
-
-Each context can have different @emph{properties}, variables contained
-in that context. They can be changed during the interpretation step.
-This is achieved by inserting the @code{\set} command in the music,
-
-@example
-\set @var{context}.@var{prop} = #@var{value}
-@end example
-
-For example,
-@lilypond[quote,verbatim,relative=2,fragment]
-R1*2
-\set Score.skipBars = ##t
-R1*2
-@end lilypond
-
-This command skips measures that have no notes. The result is that
-multi-rests are condensed. The value assigned is a Scheme object. In
-this case, it is @code{#t}, the boolean True value.
-
-If the @var{context} argument is left out, then the current bottom-most
-context (typically @context{ChordNames}, @context{Voice}, or
-@context{Lyrics}) is used. In this example,
-
-@lilypond[quote,verbatim,relative=2,fragment]
-c8 c c c
-\set autoBeaming = ##f
-c8 c c c
-@end lilypond
-
-@noindent
-the @var{context} argument to @code{\set} is left out, so automatic
-beaming is switched off in the current @internalsref{Voice}. Note that
-the bottom-most context does not always contain the property that you
-wish to change -- for example, attempting to set the @code{skipBars}
-property (of the bottom-most context, in this case @code{Voice}) will
-have no effect.
-
-@lilypond[quote,verbatim,relative=2,fragment]
-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
-@q{on-the-fly}, during the music, so that the setting only affects the
-second group of eighth notes.
-
-@funindex \unset
-
-There is also an @code{\unset} command,
-@example
-\unset @var{context}.@var{prop}
-@end example
-
-@noindent
-which removes the definition of @var{prop}. This command removes
-the definition only if it is set in @var{context}, so
-
-@example
-\set Staff.autoBeaming = ##f
-@end example
-
-@noindent
-introduces a property setting at @code{Staff} level. The setting also
-applies to the current @code{Voice}. However,
-
-@example
-\unset Voice.autoBeaming
-@end example
-
-@noindent
-does not have any effect. To cancel this setting, the @code{\unset}
-must be specified on the same level as the original @code{\set}. In
-other words, undoing the effect of @code{Staff.autoBeaming = ##f}
-requires
-@example
-\unset Staff.autoBeaming
-@end example
-
-Like @code{\set}, the @var{context} argument does not have to be
-specified for a bottom context, so the two statements
-
-@example
-\set Voice.autoBeaming = ##t
-\set autoBeaming = ##t
-@end example
-
-@noindent
-are equivalent.
-
-
-@cindex \once
-Settings that should only apply to a single time-step can be entered
-with @code{\once}, for example in
-
-@lilypond[quote,verbatim,relative=2,fragment]
-c4
-\once \set fontSize = #4.7
-c4
-c4
-@end lilypond
-
-the property @code{fontSize} is unset automatically after the second
-note.
-
-A full description of all available context properties is in the
-program reference, see
-@ifhtml
-@internalsref{Tunable context properties}.
-@end ifhtml
-@ifnothtml
-Translation @expansion{} Tunable context properties.
-@end ifnothtml
-
-
@node Modifying context plug-ins
@subsection Modifying context plug-ins
For a full a description of each plug-in, see
@ifhtml
-@internalsref{Engravers}.
+@rinternals{Engravers and Performers}.
@end ifhtml
@ifnothtml
Internals Reference @expansion{} Translation @expansion{} Engravers.
@end ifnothtml
Every context described in
@ifhtml
-@internalsref{Contexts}
+@rinternals{Contexts}
@end ifhtml
@ifnothtml
Internals Reference @expansion{} Translation @expansion{} Context.
In the second staff there are no time signature or clef symbols. This
is a rather crude method of making objects disappear since it will affect
the entire staff. This method also influences the spacing, which may or
-may not be desirable. A more
-sophisticated method of blanking objects is shown in @rlearning{Common tweaks}.
+may not be desirable. More sophisticated methods of blanking objects
+are shown in @rlearning{Visibility and color of objects}.
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_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
+within the measure, etc. By moving these engraver from @code{Score} to
@code{Staff} context, we can have a score where each staff has its own
time signature.
@end lilypond
-@node Layout tunings within contexts
-@subsection Layout tunings within contexts
-
-Each context is responsible for creating certain types of graphical
-objects. The settings used for printing these objects are also stored by
-context. By changing these settings, the appearance of objects can be
-altered.
+@node Changing context default settings
+@subsection Changing context default settings
-The syntax for this is
+The adjustments of the previous subsections (
+@ref{The \set command}, @ref{Modifying context plug-ins}, and
+@ref{Overview of modifying properties}) can also be entered
+separately from the music in the @code{\layout} block,
@example
-\override @var{context}.@var{name} #'@var{property} = #@var{value}
-@end example
+\layout @{
+ @dots{}
+ \context @{
+ \Staff
-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 (@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
-@var{value}. Here we only discuss the functionality of this command.
+ \set fontSize = #-2
+ \override Stem #'thickness = #4.0
+ \remove "Time_signature_engraver"
+ @}
+@}
+@end example
-The command
+The @code{\Staff} command brings in the existing definition of the
+staff context so that it can be modified.
-@verbatim
-\override Staff.Stem #'thickness = #4.0
-@end verbatim
+The statements
+@example
+\set fontSize = #-2
+\override Stem #'thickness = #4.0
+\remove "Time_signature_engraver"
+@end example
@noindent
-makes stems thicker (the default is 1.3, with staff line thickness as a
-unit). Since the command specifies @context{Staff} as context, it only
-applies to the current staff. Other staves will keep their normal
-appearance. Here we see the command in action:
+affect all staves in the score. Other contexts can be modified
+analogously.
-@lilypond[quote,verbatim,relative=2,fragment]
-c4
-\override Staff.Stem #'thickness = #4.0
-c4
-c4
-c4
-@end lilypond
+The @code{\set} keyword is optional within the @code{\layout} block, so
-The @code{\override} command changes the definition of the @code{Stem}
-within the current @context{Staff}. After the command is interpreted
-all stems are thickened.
+@example
+\context @{
+ @dots{}
+ fontSize = #-2
+@}
+@end example
-Analogous to @code{\set}, the @var{context} argument may be left out,
-causing the default context @context{Voice} to be used. Adding
-@code{\once} applies the change during one timestep only.
+@noindent
+will also work.
-@lilypond[quote,fragment,verbatim,relative=2]
-c4
-\once \override Stem #'thickness = #4.0
-c4
-c4
-@end lilypond
-The @code{\override} must be done before the object is
-started. Therefore, when altering @emph{Spanner} objects such as slurs
-or beams, the @code{\override} command must be executed at the moment
-when the object is created. In this example,
-@lilypond[quote,fragment,verbatim,relative=2]
-\override Slur #'thickness = #3.0
-c8[( c
-\override Beam #'thickness = #0.6
-c8 c])
-@end lilypond
+@knownissues
-@noindent
-the slur is fatter but the beam is not. This is because the command for
-@code{Beam} comes after the Beam is started, so it has no effect.
+It is not possible to collect context changes in a variable and apply
+them to a @code{\context} definition by referring to that variable.
-Analogous to @code{\unset}, the @code{\revert} command for a context
-undoes an @code{\override} command; like with @code{\unset}, it only
-affects settings that were made in the same context. In other words, the
-@code{\revert} in the next example does not do anything.
-
-@example
-\override Voice.Stem #'thickness = #4.0
-\revert Staff.Stem #'thickness
-@end example
-
-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
-@example
-\override @var{context}.@var{name} #'@var{property} #'@var{subproperty} = #@var{value}
-@end example
-
-@noindent
-such as
-
-@example
-\override Stem #'details #'beamed-lengths = #'(4 4 3)
-@end example
-
-
-@seealso
-
-Internals: @internalsref{OverrideProperty}, @internalsref{RevertProperty},
-@internalsref{PropertySet}, @internalsref{Backend}, and
-@internalsref{All layout objects}.
-
-
-@refbugs
-
-The back-end is not very strict in type-checking object properties.
-Cyclic references in Scheme values for properties can cause hangs
-or crashes, or both.
-
-
-@node Changing context default settings
-@subsection Changing context default settings
-
-The adjustments of the previous subsections (@ref{Changing context
-properties on the fly}, @ref{Modifying context plug-ins}, and
-@ref{Layout tunings within contexts}) can also be entered separately
-from the music in the @code{\layout} block,
+The @code{\RemoveEmptyStaffContext} will overwrite your current
+@code{\Staff} settings. If you wish to change the defaults for a
+staff which uses @code{\RemoveEmptyStaffContext}, you must do so
+after calling @code{\RemoveEmptyStaffContext}, ie
@example
\layout @{
- @dots{}
\context @{
- \Staff
+ \RemoveEmptyStaffContext
- \set fontSize = #-2
\override Stem #'thickness = #4.0
- \remove "Time_signature_engraver"
@}
@}
@end example
-The @code{\Staff} command brings in the existing definition of the
-staff context so that it can be modified.
-
-The statements
-@example
-\set fontSize = #-2
-\override Stem #'thickness = #4.0
-\remove "Time_signature_engraver"
-@end example
-
-@noindent
-affect all staves in the score. Other contexts can be modified
-analogously.
-
-The @code{\set} keyword is optional within the @code{\layout} block, so
-
-@example
-\context @{
- @dots{}
- fontSize = #-2
-@}
-@end example
-
-@noindent
-will also work.
-
-
-
-@refbugs
-
-It is not possible to collect context changes in a variable and apply
-them to a @code{\context} definition by referring to that variable.
-
-The @code{\RemoveEmptyStaffContext} will overwrite your current
-@code{\Staff} settings. If you wish to change the defaults for a
-staff which uses @code{\RemoveEmptyStaffContext}, you must do so
-after calling @code{\RemoveEmptyStaffContext}, ie
-
-@example
-\layout @{
- \context @{
- \RemoveEmptyStaffContext
+TODO: add \with in here.
- \override Stem #'thickness = #4.0
- @}
-@}
-@end example
@node Defining new contexts
@subsection Defining new contexts
-Specific contexts, like @context{Staff} and @code{Voice}, are made of
+Specific contexts, like @code{Staff} and @code{Voice}, are made of
simple building blocks. It is possible to create new types of
contexts with different combinations of engraver plug-ins.
The next example shows how to build a different type of
-@context{Voice} context from scratch. It will be similar to
-@code{Voice}, but only prints centered slash noteheads. It can be used
+@code{Voice} context from scratch. It will be similar to
+@code{Voice}, but only prints centered slash note heads. It can be used
to indicate improvisation in jazz pieces,
@lilypond[quote,ragged-right]
\name ImproVoice
@end example
-Since it is similar to the @context{Voice}, we want commands that work
-on (existing) @context{Voice}s to remain working. This is achieved by
-giving the new context an alias @context{Voice},
+Since it is similar to the @code{Voice}, we want commands that work
+on (existing) @code{Voice}s to remain working. This is achieved by
+giving the new context an alias @code{Voice},
@example
\alias Voice
squashedPosition = #0
@end example
-The @internalsref{Pitch_squash_engraver} modifies note heads (created
-by @internalsref{Note_heads_engraver}) and sets their vertical
+The @rinternals{Pitch_squash_engraver} modifies note heads (created
+by @rinternals{Note_heads_engraver}) and sets their vertical
position to the value of @code{squashedPosition}, in this case@tie{}@code{0},
the center line.
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},
+This should always be @rinternals{Engraver_group},
@example
\type "Engraver_group"
@end example
@funindex \accepts
-Contexts form hierarchies. We want to hang the @context{ImproVoice}
-under @context{Staff}, just like normal @code{Voice}s. Therefore, we
+Contexts form hierarchies. We want to hang the @code{ImproVoice}
+under @code{Staff}, just like normal @code{Voice}s. Therefore, we
modify the @code{Staff} definition with the @code{\accepts}
command,
@node Aligning contexts
@subsection Aligning contexts
-New contexts may be aligned above or below exisiting contexts. This
+New contexts may be aligned above or below existing contexts. This
could be useful in setting up a vocal staff (@rlearning{Vocal ensembles}) and
in ossia,
+FIXME: this section doesn't work in pdf. (?)
+
@cindex ossia
@findex alignAboveContext
@findex alignBelowContext
@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 @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. The
-general syntax of this command is:
-
-@example
-\override @var{context}.@var{layout_object} #'@var{layout_property} = #@var{value}
-@end example
+@node Explaining the Internals Reference
+@section Explaining the Internals Reference
-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::
* Navigating the program reference::
* Layout interfaces::
* Determining the grob property::
-* Objects connected to the input::
-* Using Scheme code instead of \tweak::
-* \set versus \override::
-* Difficult tweaks::
+* Naming conventions::
@end menu
-
-
-@node Constructing a tweak
-@subsection Constructing a tweak
-
-Commands which change output generally look like
-
-@example
-\override Voice.Stem #'thickness = #3.0
-@end example
-
-@noindent
-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
-
-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
-@cindex tweaking
-@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
@ref{Fingering instructions}), you will notice:
@quotation
-@seealso
+@strong{See also}
-Internals Reference: @internalsref{Fingering}.
+Internals Reference: @rinternals{Fingering}.
@end quotation
forward. For example, it says
@quotation
-Accepted by: @internalsref{Fingering_engraver},
+Accepted by: @rinternals{Fingering_engraver},
@end quotation
@noindent
plug-in, which says
@quotation
-This engraver creates the following layout objects: @internalsref{Fingering}.
+This engraver creates the following layout objects: @rinternals{Fingering}.
@end quotation
In other words, once the @code{FingerEvent}s are interpreted, the
@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,
+@rinternals{Fingering} objects,
@c old info? it doesn't make any sense to me with our current docs.
This is also the
PDF manual.
@end ifnothtml
-Follow the link to @internalsref{Fingering}. At the top of the
+Follow the link to @rinternals{Fingering}. At the top of the
page, you will see
@quotation
-Fingering objects are created by: @internalsref{Fingering_engraver} and
-@internalsref{New_fingering_engraver}.
+Fingering objects are created by: @rinternals{Fingering_engraver} and
+@rinternals{New_fingering_engraver}.
@end quotation
By following related links inside the program reference, we can follow the
@itemize
-@item @internalsref{Fingering}:
-@internalsref{Fingering} objects are created by:
-@internalsref{Fingering_engraver}
+@item @rinternals{Fingering}:
+@rinternals{Fingering} objects are created by:
+@rinternals{Fingering_engraver}
-@item @internalsref{Fingering_engraver}:
-Music types accepted: @internalsref{fingering-event}
+@item @rinternals{Fingering_engraver}:
+Music types accepted: @rinternals{fingering-event}
-@item @internalsref{fingering-event}:
+@item @rinternals{fingering-event}:
Music event type @code{fingering-event} is in Music expressions named
-@internalsref{FingerEvent}
+@rinternals{FingerEvent}
@end itemize
This path goes against the flow of information in the program: it
The program reference can also be browsed like a normal document. It
contains chapters on
@ifhtml
-@internalsref{Music definitions},
+@rinternals{Music definitions},
@end ifhtml
@ifnothtml
@code{Music definitions}
@end ifnothtml
-on @internalsref{Translation}, and the @internalsref{Backend}. Every
+on @rinternals{Translation}, and the @rinternals{Backend}. Every
chapter lists all the definitions used and all properties that may be
tuned.
@cindex grob
The HTML page that we found in the previous section describes the
-layout object called @internalsref{Fingering}. Such an object is a
+layout object called @rinternals{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 a @emph{Grob}, which is short for Graphical
-Object. For more details about Grobs, see @internalsref{grob-interface}.
+Object. For more details about Grobs, see @rinternals{grob-interface}.
The page for @code{Fingering} lists the definitions for the
@code{Fingering} object. For example, the page says
@item
Horizontally, the center of the symbol should be aligned to the
-center of the notehead.
+center of the note head.
@item
Vertically, the symbol is placed next to the note and the staff.
@end itemize
Each of these aspects is captured in so-called @emph{interface}s,
-which are listed on the @internalsref{Fingering} page at the bottom
+which are listed on the @rinternals{Fingering} page at the bottom
@quotation
This object supports the following interfaces:
-@internalsref{item-interface},
-@internalsref{self-alignment-interface},
-@internalsref{side-position-interface}, @internalsref{text-interface},
-@internalsref{text-script-interface}, @internalsref{font-interface},
-@internalsref{finger-interface}, and @internalsref{grob-interface}.
+@rinternals{item-interface},
+@rinternals{self-alignment-interface},
+@rinternals{side-position-interface}, @rinternals{text-interface},
+@rinternals{text-script-interface}, @rinternals{font-interface},
+@rinternals{finger-interface}, and @rinternals{grob-interface}.
@end quotation
Clicking any of the links will take you to the page of the respective
We have been talking of @emph{the} @code{Fingering} object, but actually it
does not amount to much. The initialization file (see
-@rlearning{Default files})
+@rlearning{Other sources of information})
@file{scm/@/define@/-grobs@/.scm} shows the soul of the @q{object},
@example
@end quotation
By increasing the value of @code{padding}, we can move the
-fingering away from the notehead. The following command inserts
+fingering away from the note head. The following command inserts
3 staff spaces of white
between the note and the fingering:
@example
@end lilypond
-In this case, the context for this tweak is @context{Voice}. This
+In this case, the context for this tweak is @code{Voice}. This
fact can also be deduced from the program reference, for the page for
-the @internalsref{Fingering_engraver} plug-in says
+the @rinternals{Fingering_engraver} plug-in says
@quotation
-Fingering_engraver is part of contexts: @dots{} @internalsref{Voice}
+Fingering_engraver is part of contexts: @dots{} @rinternals{Voice}
@end quotation
-@node Objects connected to the input
-@subsection Objects connected to the input
+@node Naming conventions
+@subsection Naming conventions
-@funindex \tweak
+Another thing that is needed, is an overview of the various naming
+conventions:
-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
+ scheme functions: lowercase-with-hyphens (incl. one-word
+names)
+ scheme functions: ly:plus-scheme-style
+ music events, music classes and music properties:
+as-scheme-functions
+ Grob interfaces: scheme-style
+ backend properties: scheme-style (but X and Y!)
+ contexts (and MusicExpressions and grobs): Capitalized or
+CamelCase
+ context properties: lowercaseFollowedByCamelCase
+ engravers:
+Capitalized_followed_by_lowercase_and_with_underscores
-@lilypond[relative=2,fragment,verbatim,ragged-right]
-<
- c
- \tweak #'color #red d
- g
- \tweak #'duration-log #1 a
->4-\tweak #'padding #10 -.
-@end lilypond
+Which of these are conventions and which are rules?
+Which are rules of the underlying language, and which are
+LP-specific?
-As you can see, properties are set in the objects directly,
-without mentioning the grob name or context where this should be
-applied.
-This technique only works for objects that are directly connected to
-an @internalsref{Event} from the input, for example
+@node Modifying properties
+@section Modifying properties
-@itemize
-@item note heads, caused by chord-pitch (i.e., notes inside a chord)
-@item articulation signs, caused by articulation instructions
-@end itemize
+@menu
+* Overview of modifying properties::
+* The \set command::
+* The \override command::
+* \set versus \override::
+* Objects connected to the input::
+@end menu
-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).
-There are very few objects which are @emph{directly} connected to
-output. A normal note (like @code{c4}) is not directly connected
-to output, so
+@node Overview of modifying properties
+@subsection Overview of modifying properties
+
+Each context is responsible for creating certain types of graphical
+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
-\tweak #'color #red c4
+\override @var{context}.@var{name} #'@var{property} = #@var{value}
@end 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 (@q{grob property} or @q{layout
+property}). The latter is a symbol, so it must be quoted. The
+subsection @ref{Modifying properties}, 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
+@end verbatim
+
@noindent
-does not change color. See @ref{Displaying music expressions}, for
-details.
+makes stems thicker (the default is 1.3, with staff line thickness as a
+unit). Since the command specifies @code{Staff} as context, it only
+applies to the current staff. Other staves will keep their normal
+appearance. Here we see the command in action:
+@lilypond[quote,verbatim,relative=2,fragment]
+c4
+\override Staff.Stem #'thickness = #4.0
+c4
+c4
+c4
+@end lilypond
-@node Using Scheme code instead of \tweak
-@subsection Using Scheme code instead of @code{\tweak}
+The @code{\override} command changes the definition of the @code{Stem}
+within the current @code{Staff}. After the command is interpreted
+all stems are thickened.
-The main disadvantage of @code{\tweak} is its syntactical
-inflexibility. For example, the following produces a syntax error.
+Analogous to @code{\set}, the @var{context} argument may be left out,
+causing the default context @code{Voice} to be used. Adding
+@code{\once} applies the change during one timestep only.
-@example
-F = \tweak #'font-size #-3 -\flageolet
+@lilypond[quote,fragment,verbatim,relative=2]
+c4
+\once \override Stem #'thickness = #4.0
+c4
+c4
+@end lilypond
-\relative c'' @{
- c4^\F c4_\F
-@}
-@end example
+The @code{\override} must be done before the object is
+started. Therefore, when altering @emph{Spanner} objects such as slurs
+or beams, the @code{\override} command must be executed at the moment
+when the object is created. In this example,
+
+@lilypond[quote,fragment,verbatim,relative=2]
+\override Slur #'thickness = #3.0
+c8[( c
+\override Beam #'thickness = #0.6
+c8 c])
+@end lilypond
@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{_}.
+the slur is fatter but the beam is not. This is because the command for
+@code{Beam} comes after the Beam is started, so it has no effect.
-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.
+Analogous to @code{\unset}, the @code{\revert} command for a context
+undoes an @code{\override} command; like with @code{\unset}, it only
+affects settings that were made in the same context. In other words, the
+@code{\revert} in the next example does not do anything.
@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
-@}
+\override Voice.Stem #'thickness = #4.0
+\revert Staff.Stem #'thickness
@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.
+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
+@example
+\override @var{context}.@var{name} #'@var{property} #'@var{subproperty} = #@var{value}
+@end example
-@node \set versus \override
-@subsection @code{\set} vs. @code{\override}
+@noindent
+such as
+
+@example
+\override Stem #'details #'beamed-lengths = #'(4 4 3)
+@end example
+
+
+@seealso
+
+Internals: @rinternals{OverrideProperty}, @rinternals{RevertProperty},
+@rinternals{PropertySet}, @rinternals{Backend}, and
+@rinternals{All layout objects}.
+
+
+@knownissues
+
+The back-end is not very strict in type-checking object properties.
+Cyclic references in Scheme values for properties can cause hangs
+or crashes, or both.
+
+
+
+@node The \set command
+@subsection The @code{\set} command
+
+@cindex properties
+@funindex \set
+@cindex changing properties
+
+Each context can have different @emph{properties}, variables contained
+in that context. They can be changed during the interpretation step.
+This is achieved by inserting the @code{\set} command in the music,
+
+@example
+\set @var{context}.@var{prop} = #@var{value}
+@end example
+
+For example,
+@lilypond[quote,verbatim,relative=2,fragment]
+R1*2
+\set Score.skipBars = ##t
+R1*2
+@end lilypond
+
+This command skips measures that have no notes. The result is that
+multi-rests are condensed. The value assigned is a Scheme object. In
+this case, it is @code{#t}, the boolean True value.
+
+If the @var{context} argument is left out, then the current bottom-most
+context (typically @code{ChordNames}, @code{Voice}, or
+@code{Lyrics}) is used. In this example,
+
+@lilypond[quote,verbatim,relative=2,fragment]
+c8 c c c
+\set autoBeaming = ##f
+c8 c c c
+@end lilypond
+
+@noindent
+the @var{context} argument to @code{\set} is left out, so automatic
+beaming is switched off in the current @rinternals{Voice}. Note that
+the bottom-most context does not always contain the property that you
+wish to change -- for example, attempting to set the @code{skipBars}
+property (of the bottom-most context, in this case @code{Voice}) will
+have no effect.
+
+@lilypond[quote,verbatim,relative=2,fragment]
+R1*2
+\set skipBars = ##t
+R1*2
+@end lilypond
+
+Contexts are hierarchical, so if a bigger context was specified, for
+example @code{Staff}, then the change would also apply to all
+@code{Voice}s in the current stave. The change is applied
+@q{on-the-fly}, during the music, so that the setting only affects the
+second group of eighth notes.
+
+@funindex \unset
+
+There is also an @code{\unset} command,
+@example
+\unset @var{context}.@var{prop}
+@end example
+
+@noindent
+which removes the definition of @var{prop}. This command removes
+the definition only if it is set in @var{context}, so
+
+@example
+\set Staff.autoBeaming = ##f
+@end example
+
+@noindent
+introduces a property setting at @code{Staff} level. The setting also
+applies to the current @code{Voice}. However,
+
+@example
+\unset Voice.autoBeaming
+@end example
+
+@noindent
+does not have any effect. To cancel this setting, the @code{\unset}
+must be specified on the same level as the original @code{\set}. In
+other words, undoing the effect of @code{Staff.autoBeaming = ##f}
+requires
+@example
+\unset Staff.autoBeaming
+@end example
+
+Like @code{\set}, the @var{context} argument does not have to be
+specified for a bottom context, so the two statements
+
+@example
+\set Voice.autoBeaming = ##t
+\set autoBeaming = ##t
+@end example
+
+@noindent
+are equivalent.
+
+
+@cindex \once
+Settings that should only apply to a single time-step can be entered
+with @code{\once}, for example in
+
+@lilypond[quote,verbatim,relative=2,fragment]
+c4
+\once \set fontSize = #4.7
+c4
+c4
+@end lilypond
+
+the property @code{fontSize} is unset automatically after the second
+note.
+
+A full description of all available context properties is in the
+program reference, see
+@ifhtml
+@rinternals{Tunable context properties}.
+@end ifhtml
+@ifnothtml
+Translation @expansion{} Tunable context properties.
+@end ifnothtml
+
+
+
+@node The \override command
+@subsection The @code{\override} command
+
+Commands which change output generally look like
+
+@example
+\override Voice.Stem #'thickness = #3.0
+@end example
+
+@noindent
+To construct this tweak we must determine these bits of information:
+
+@itemize
+@item the context: here @code{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
+
+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
+@cindex tweaking
+@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 \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
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
+music to notation, eg. @code{localKeySignature} (for determining
whether to print accidentals), @code{measurePosition} (for
-determining when to print a barline). Context properties can
+determining when to print a bar line). 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}.
\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 value of @code{context} (the alist) is used to initialize
the properties of individual grobs. Grobs also have
properties, named in Scheme style, with
@code{dashed-words}. The values of grob properties change
property (modified with @code{\set}) was created.
-@node Difficult tweaks
-@subsection Difficult tweaks
-
-There are a few classes of difficult adjustments.
+@node Objects connected to the input
+@subsection Objects connected to the input
-@itemize
+TODO: can't use \tweak in a variable
+@funindex \tweak
-@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
-are cloned. A separate object is created for every system that it is
-in. These are clones of the original object and inherit all
-properties, including @code{\override}s.
+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
+@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 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 contains the Scheme procedure that
-is called after the line breaks have been determined, and layout
-objects have been split over different systems.
+As you can see, properties are set in the objects directly,
+without mentioning the grob name or context where this should be
+applied.
-In the following example, we define a procedure
-@code{my-callback}. This procedure
+This technique only works for objects that are directly connected to
+an @rinternals{Event} from the input, for example
@itemize
-@item
-determines if we have been split across line breaks
-@item
-if yes, retrieves all the split objects
-@item
-checks if we are the last of the split objects
-@item
-if yes, it sets @code{extra-offset}.
+@item note heads, caused by chord-pitch (i.e., notes inside a chord)
+@item articulation signs, caused by articulation instructions
@end itemize
-This procedure is installed into @internalsref{Tie}, so the last part
-of the broken tie is translated up.
+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).
+
+There are very few objects which are @emph{directly} connected to
+output. A normal note (like @code{c4}) is not directly connected
+to output, so
-@lilypond[quote,verbatim,ragged-right]
-#(define (my-callback grob)
- (let* (
- ; have we been split?
- (orig (ly:grob-original grob))
+@example
+\tweak #'color #red c4
+@end example
+
+@noindent
+does not change color. See @ref{Displaying music expressions}, for
+details.
- ; if yes, get the split pieces (our siblings)
- (siblings (if (ly:grob? orig)
- (ly:spanner-broken-into orig) '() )))
- (if (and (>= (length siblings) 2)
- (eq? (car (last-pair siblings)) grob))
- (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
+@node Useful concepts and properties
+@section Useful concepts and properties
-\relative c'' {
- \override Tie #'after-line-breaking =
- #my-callback
- c1 ~ \break c2 ~ c
+
+@menu
+* Input modes::
+* Direction and placement::
+* Distances and measurements::
+* Spanners::
+@end menu
+
+@node Input modes
+@subsection Input modes
+
+The way in which the notation contained within an input file is
+interpreted is determined by the current input mode.
+
+@strong{Chord mode}
+
+This is activated with the @code{\chordmode} command, and causes
+input to be interpreted with the syntax of chord notation, see
+@ref{Chord notation}. Chords are rendered as notes on a staff.
+
+Chord mode is also activated with the @code{\chords} command.
+This also creates a new @code{ChordNames} context and
+causes the following input to be interpreted with the syntax of
+chord notation and rendered as chord names in the @code{ChordNames}
+context, see @ref{Printing chord names}.
+
+@strong{Drum mode}
+
+This is activated with the @code{\drummode} command, and causes
+input to be interpreted with the syntax of drum notation, see
+@ref{Basic percussion notation}.
+
+Drum mode is also activated with the @code{\drums} command.
+This also creates a new @code{DrumStaff} context and causes the
+following input to be interpreted with the syntax of drum notation
+and rendered as drum symbols on a drum staff, see @ref{Basic
+percussion notation}.
+
+@strong{Figure mode}
+
+This is activated with the @code{\figuremode} command, and causes
+input to be interpreted with the syntax of figured bass, see
+@ref{Entering figured bass}.
+
+Figure mode is also activated with the @code{\figures} command.
+This also creates a new @code{FiguredBass} context and causes the
+following input to be interpreted with the figured bass syntax
+and rendered as figured bass symbols in the @code{FiguredBass}
+context, see @ref{Introduction to figured bass}.
+
+@strong{Fret and tab modes}
+
+There are no special input modes for entering fret and tab symbols.
+
+To create tab diagrams, enter notes or chords in note mode and
+render them in a @code{TabStaff} context, see
+@ref{Default tablatures}.
+
+To create fret diagrams above a staff, enter them as markup
+above the notes using the @code{\fret-diagram} command, see
+@ref{Fret diagrams}.
+
+@strong{Lyrics mode}
+
+This is activated with the @code{\lyricmode} command, and causes
+input to be interpreted as lyric syllables with optional durations
+and associated lyric modifiers, see @ref{Vocal music}.
+
+Lyric mode is also activated with the @code{\addlyrics} command.
+This also creates a new @code{Lyrics} context and an implicit
+@code{\lyricsto} command which associates the following lyrics
+with the preceding music.
+
+@strong{Markup mode}
+
+This is activated with the @code{\markup} command, and causes
+input to be interpreted with the syntax of markup, see
+@ref{Text markup commands}.
+
+@c silly work-around for texinfo broken-ness
+@c (@strong{Note...} causes a spurious cross-reference in Info)
+@b{Note mode}
+
+This is the default mode or it may be activated with the
+@code{\notemode} command. Input is interpreted as pitches,
+durations, markup, etc and typeset as musical notation on a staff.
+
+It is not normally necessary to specify note mode explicitly, but
+it may be useful to do so in certain situations, for example if you
+are in lyric mode, chord mode or any other mode and want to insert
+something that only can be done with note mode syntax.
+
+For example, to indicate dynamic markings for the verses of a
+choral pieces it is necessary to enter note mode to interpret
+the markings:
+
+@lilypond[verbatim,relative=2,quote]
+{ c4 c4 c4 c4 }
+\addlyrics {
+ \notemode{\set stanza = \markup{ \dynamic f 1. } }
+ To be sung loudly
+}
+\addlyrics {
+ \notemode{\set stanza = \markup{ \dynamic p 2. } }
+ To be sung quietly
}
@end lilypond
+
+
+@node Direction and placement
+@subsection Direction and placement
+
+In typesetting music the direction and placement of many items is
+a matter of choice. For example, the stems of notes can
+be directed up or down; lyrics, dynamics, and other expressive
+marks may be placed above or below the staff; text may be aligned
+left, right or center; etc. Most of these choices may be left to
+be determined automatically by LilyPond, but in some cases it may
+be desirable to force a particular direction or placement.
+
+@strong{Default actions}
+
+By default some directions are always up or always down (e.g.
+dynamics or fermata), while other things can alternate between
+up or down based on the stem direction (like slurs or accents).
+
+@c TODO Add table showing these
+
+@strong{Context layout}
+
+Contexts are positioned in a system from top to bottom in the
+order in which they are encountered. Note, however, that a
+context will be created implicitly if a command is encountered
+when there is no suitable context available to contain it.
+
+@c TODO Add example ?
+
+The default order in which contexts are laid out can be changed,
+see @ref{Aligning contexts}
+
+@strong{Articulation direction indicators}
+
+When adding articulations to notes the direction indicator,
+@code{^} (meaning @qq{up}), @code{_} (meaning @qq{down}) or
+@code{-} (meaning @qq{use default direction}), can usually be
+omitted, in which case @code{-} is assumed. But a direction
+indicator is @strong{always} required before
+
+@itemize
+@item @code{\tweak} commands
+@item @code{\markup} commands
+@item @code{\tag} commands
+@item string markups, e.g. -"string"
+@item fingering instructions, e.g. @code{-1}
+@item articulation shortcuts, e.g. @code{-.}, @code{->}, @code{--}
+@end itemize
+
+@strong{The direction property}
+
+The position or direction of many layout objects is controlled
+by the @code{direction} property.
+
+The value of the @code{direction} property may be
+set to @code{1}, meaning @qq{up} or @qq{above}, or to @code{-1},
+meaning @qq{down} or @qq{below}. The symbols @code{UP} and
+@code{DOWN} may be used instead of @code{1} and @code{-1}
+respectively. The default direction may be specified by setting
+@code{direction} to @code{0} or @code{CENTER}. Alternatively,
+in many cases predefined commands
+exist to specify the direction. These are all of the form
+
@noindent
-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.
+@code{\xxxUp}, @code{xxxDown}, @code{xxxNeutral}
+
+@noindent
+where @code{xxxNeutral} means @qq{use the default direction}.
+See @rlearning{Within-staff objects}.
+
+In a few cases, arpeggio being the only common example, the value
+of the @code{direction} property specifies whether the object
+is to be placed to the right or left of the parent object. In
+this case @code{-1} or @code{LEFT} means @qq{to the left} and
+@code{1} or @code{RIGHT} means @qq{to the right}. @code{0}
+or @code{CENTER} means @qq{use the default} direction, as before.
+
+@ignore
+These all have side-axis set to #X
+AmbitusAccidental - direction has no effect
+Arpeggio - works
+StanzaNumber - not tried
+TrillPitchAccidental - not tried
+TrillPitchGroup - not tried
+@end ignore
+
+
+
+@node Distances and measurements
+@subsection Distances and measurements
+
+DISCUSS after working on other sections.
+
+TODO: staff spaces. Maybe move into tweaks?
+
+
+@node Spanners
+@subsection Spanners
+
+Many objects of musical notation extend over several notes or even
+several bars. Examples are crescendi, trills, tuplet brackets, and
+volta repeat brackets. Such objects are called @qq{spanners}, and
+have special properties to control their appearance and behaviour.
+Some of these properties are common to all spanners; others are
+restricted to a sub-set of the spanners.
+
+
+@node Common properties
+@section Common properties
+
+@menu
+* Controlling visibility of objects::
+* Line styles::
+* Rotating objects::
+* Aligning objects::
+@end menu
+
+@node Controlling visibility of objects
+@subsection Controlling visibility of objects
+
+
+@node Line styles
+@subsection Line styles
+
+@c TODO: split the following explanations between expressive marks and
+@c text-related stuff. Perhaps create a new subsection named
+@c "Spanner limits", "Spanner boundaries"? -vv
+
+Some performance indications, e.g., @i{rallentando} and
+@i{accelerando} and @i{trills} are written as text and are
+extended over many measures with lines, sometimes dotted or wavy.
+
+These all use the same routines as the glissando for drawing the
+texts and the lines, and tuning their behavior is therefore also
+done in the same way. It is done with a spanner, and the routine
+responsible for drawing the spanners is
+@code{ly:line-interface::print}. This routine determines the
+exact location of the two @i{span points} and draws a line in
+between, in the style requested.
+
+Here is an example of the different line styles available, and how
+to tune them.
+
+@lilypond[relative=2,ragged-right,verbatim,fragment]
+d2 \glissando d'2
+\once \override Glissando #'style = #'dashed-line
+d,2 \glissando d'2
+\override Glissando #'style = #'dotted-line
+d,2 \glissando d'2
+\override Glissando #'style = #'zigzag
+d,2 \glissando d'2
+\override Glissando #'style = #'trill
+d,2 \glissando d'2
+@end lilypond
+
+The information that determines the end-points is computed
+on-the-fly for every graphic object, but it is possible to
+override these.
+
+@lilypond[relative=2,ragged-right,verbatim,fragment]
+e2 \glissando f
+\once \override Glissando #'bound-details #'right #'Y = #-2
+e2 \glissando f
+@end lilypond
+
+The @code{Glissando} object, like any other using the
+@code{ly:line-interface::print} routine, carries a nested
+association list. In the above statement, the value for @code{Y}
+is set to @code{-2} for the association list corresponding to the
+right end point. Of course, it is also possible to adjust the
+left side with @code{left} instead of @code{right}.
+
+If @code{Y} is not set, the value is computed from the vertical
+position of right attachment point of the spanner.
+
+In case of a line break, the values for the span-points are
+extended with contents of the @code{left-broken} and
+@code{right-broken} sublists, for example
+
+@lilypond[relative=2,ragged-right,verbatim,fragment]
+\override Glissando #'breakable = ##T
+\override Glissando #'bound-details #'right-broken #'Y = #-3
+c1 \glissando \break
+f1
+@end lilypond
+
+The following properties can be used for the
+
+@table @code
+@item Y
+This sets the Y-coordinate of the end point, in staff space. By
+default, it is the center of the bound object, so for a glissando
+it points to the vertical center of the note head.
+
+For horizontal spanners, such as text spanner and trill spanners,
+it is hardcoded to 0.
+
+@item attach-dir
+This determines where the line starts and ends in X-direction,
+relative to the bound object. So, a value of @code{-1} (or
+@code{LEFT}) makes the line start/end at the left side of the note
+head it is attached to.
+
+@item X
+This is the absolute coordinate of the end point. It is usually
+computed on the fly, and there is little use in overriding it.
+
+@item stencil
+Line spanners may have symbols at the beginning or end, which is
+contained in this sub-property. This is for internal use, it is
+recommended to use @code{text}.
+
+@item text
+This is a markup that is evaluated to yield stencil. It is used
+to put @i{cresc.} and @i{tr} on horizontal spanners.
+
+@lilypond[quote,ragged-right,fragment,relative=2,verbatim]
+\override TextSpanner #'bound-details #'left #'text
+ = \markup { \small \bold Slower }
+c2\startTextSpan b c a\stopTextSpan
+@end lilypond
+
+@item stencil-align-dir-y
+@item stencil-offset
+Without setting this, the stencil is simply put there at the
+end-point, as defined by the @code{X} and @code{Y} sub properties.
+Setting either @code{stencil-align-dir-y} or @code{stencil-offset}
+will move the symbol at the edge relative to the end point of the
+line
+
+@lilypond[relative=1,fragment,verbatim]
+\override TextSpanner #'bound-details
+ #'left #'stencil-align-dir-y = #DOWN
+\override TextSpanner #'bound-details
+ #'right #'stencil-align-dir-y = #UP
+
+\override TextSpanner #'bound-details
+ #'left #'text = #"gggg"
+\override TextSpanner #'bound-details
+ #'right #'text = #"hhhh"
+c4^\startTextSpan c c c \stopTextSpan
+@end lilypond
+
+@item arrow
+Setting this sub property to @code{#t} produce an arrowhead at the
+end of the line.
+
+@item padding
+This sub property controls the space between the specified
+end-point of the line and the actual end. Without padding, a
+glissando would start and end in the center of each note head.
+
+@end table
+
+FIXME: should this be in NR 3?
+
+The music function \endSpanners terminates spanners and hairpins
+after exactly one note.
+
+@lilypond[verbatim,quote,ragged-right,relative=2,fragment]
+\endSpanners
+c2 \startTextSpan c2
+c2 \< c2
+@end lilypond
+When using \endSpanners it is not necessary to close
+\startTextSpan with \stopTextSpan, nor is it necessary to close
+hairpins with \!.
-@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{\overrideProperty} function, which works similar to @code{\once
-\override}, but uses a different syntax.
+
+
+@seealso
+
+Internals Reference: @rinternals{TextSpanner},
+@rinternals{Glissando}, @rinternals{VoiceFollower},
+@rinternals{TrillSpanner},
+@rinternals{line-spanner-interface}.
+
+
+@node Rotating objects
+@subsection Rotating objects
+
+@node Aligning objects
+@subsection Aligning objects
+
+
+@node Advanced tweaks
+@section Advanced tweaks
+
+@menu
+* Vertical grouping of grobs::
+* Modifying ends of spanners::
+* Modifying stencils::
+@end menu
+
+
+
+
+@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 Modifying ends of spanners
+@subsection Modifying ends of spanners
+
+
+@node Modifying stencils
+@subsection Modifying stencils
+
+
+
+@node old The \override command
+@section old 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. The
+general syntax of this command is:
@example
-\overrideProperty
-#"Score.NonMusicalPaperColumn" % Grob name
-#'line-break-system-details % Property name
-#'((next-padding . 20)) % Value
+\override @var{context}.@var{layout_object} #'@var{layout_property} = #@var{value}
@end example
-Note, however, that @code{\override}, applied to
-@code{NoteMusicalPaperColumn} and @code{PaperColumn}, still works as
-expected within @code{\context} blocks.
+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}.
+
+
+
+
+
+@node Discussion of specific tweaks
+@section Discussion of specific tweaks
+
+@menu
+* old Contexts explained::
+@end menu
+
+
+@node old Contexts explained
+@subsection old Contexts explained
+
+When music is printed, a lot of notational elements must be added to the
+output. For example, compare the input and output of the following example:
+
+@lilypond[quote,verbatim,relative=2,fragment]
+cis4 cis2. g4
+@end lilypond
+
+The input is rather sparse, but in the output, bar lines, accidentals,
+clef, and time signature are added. LilyPond @emph{interprets} the
+input. During this step, the musical information is inspected in time
+order, similar to reading a score from left to right. While reading
+the input, the program remembers where measure boundaries are, and which
+pitches require explicit accidentals. This information can be presented on
+several levels. For example, the effect of an accidental is limited
+to a single staff, while a bar line must be synchronized across the
+entire score.
+
+Within LilyPond, these rules and bits of information are grouped in
+@emph{Contexts}. Some examples of contexts are @code{Voice},
+@code{Staff}, and @code{Score}. They are hierarchical, for
+example: a @code{Staff} can contain many @code{Voice}s, and a
+@code{Score} can contain many @code{Staff} contexts.
+
+@quotation
+@sourceimage{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 @code{Voice} context may introduce an
+accidental and then the @code{Staff} context maintains the rule to
+show or suppress the accidental for the remainder of the measure. The
+synchronization of bar lines is handled at @code{Score} context.
+
+However, in some music we may not want the bar lines to be
+synchronized -- consider a polymetric score in 4/4 and 3/4 time. In
+such cases, we must modify the default settings of the @code{Score}
+and @code{Staff} contexts.
+
+For very simple scores, contexts are created implicitly, and you need
+not be aware of them. For larger pieces, such as anything with more
+than one staff, they must be
+created explicitly to make sure that you get as many staves as you
+need, and that they are in the correct order. For typesetting pieces
+with specialized notation, it can be useful to modify existing or
+to define new contexts.
+
+
+A complete description of all available contexts is in the program
+reference, see
+@ifhtml
+@rinternals{Contexts}.
+@end ifhtml
+@ifnothtml
+Translation @expansion{} Context.
+@end ifnothtml
+
+@c [TODO: describe propagation]
+
+
-@end itemize
projects / lilypond.git / blobdiff