@c -*- coding: utf-8; mode: texinfo; -*-
+@c This file is part of lilypond.tely
+@ignore
+ Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
+
+ When revising a translation, copy the HEAD committish of the
+ version that you are working on. See TRANSLATION for details.
+@end ignore
+
@node Changing defaults
@chapter Changing defaults
The purpose of LilyPond's design is to provide the finest output
quality as a default. Nevertheless, it may happen that you need to
change this default layout. The layout is controlled through a large
-number of proverbial ``knobs and switches.'' This chapter does not
+number of proverbial @q{knobs and switches.} This chapter does not
list each and every knob. Rather, it outlines what groups of controls
are available and explains how to lookup which knob to use for a
particular effect.
That manual
lists all different variables, functions and options available in
LilyPond. It is written as a HTML document, which is available
-@uref{http://@/lilypond@/.org/@/doc/@/v2.8/@/Documentation/@/user/@/
-lilypond@/-internals/,on@/-line},
+@c leave the @uref as one long line.
+@uref{http://@/lilypond@/.org/@/doc/@/stable/@/Documentation/@/user/@/lilypond@/-internals/,on@/-line},
but is also included with the LilyPond documentation package.
There are four areas where the default settings may be changed:
notation. For example, giving each staff a separate time signature.
@item
-Global layout: changing the appearance of the spacing, line
+Page layout: changing the appearance of the spacing, line
breaks, and page dimensions. These modifications are discussed
-in @ref{Global issues}.
+in @ref{Non-musical notation} and @ref{Spacing issues}.
@end itemize
Internally, LilyPond uses Scheme (a LISP dialect) to provide
Common rules for typesetting accidentals have been placed in a
function. This function is called as follows
-@cindex @code{set-accidental-style}
+@funindex set-accidental-style
@example
#(set-accidental-style 'STYLE #('CONTEXT#))
@end example
should be used instead.
@item modern
-@cindex @code{modern} style accidentals
+@funindex modern style accidentals
This rule corresponds to the common practice in the 20th century. This rule
prints the same accidentals as @code{default}, but temporary
accidentals also are canceled in other octaves. Furthermore,
@end lilypond
@item @code{modern-cautionary}
-@cindex @code{modern-cautionary}
-This rule is similar to @code{modern}, but the ``extra'' accidentals
+@funindex modern-cautionary
+This rule is similar to @code{modern}, but the @q{extra} accidentals
(the ones not typeset by @code{default}) are typeset as cautionary
accidentals. They are printed in reduced size or with parentheses
@lilypond[quote,ragged-right,fragment,verbatim]
cis' c'' cis'2 | c'' c'
@end lilypond
-@cindex @code{modern-voice}
+@funindex modern-voice
@item modern-voice
This rule is used for multivoice accidentals to be read both by musicians
playing one voice and musicians playing all voices. Accidentals are
typeset for each voice, but they @emph{are} canceled across voices in
the same @internalsref{Staff}.
-@cindex @code{modern-voice-cautionary}
+@funindex modern-voice-cautionary
@item modern-voice-cautionary
This rule is the same as @code{modern-voice}, but with the extra
accidentals (the ones not typeset by @code{voice}) typeset
some of them are typeset as cautionaries.
@item piano
-@cindex @code{piano} accidentals
+@funindex piano accidentals
This rule reflects 20th century practice for piano notation. Very similar to
@code{modern} but accidentals also get canceled
across the staves in the same @internalsref{GrandStaff} or
@internalsref{PianoStaff}.
@item piano-cautionary
-@cindex @code{#(set-accidental-style 'piano-cautionary)}
+@funindex #(set-accidental-style 'piano-cautionary)
Same as @code{#(set-accidental-style 'piano)} but with the extra
accidentals typeset as cautionaries.
@item no-reset
-@cindex @code{no-reset} accidental style
+@funindex no-reset accidental style
This is the same as @code{default} but with accidentals lasting
-``forever'' and not only until the next measure
+@q{forever} and not only until the next measure
@lilypond[quote,ragged-right,fragment,verbatim,relative=1]
#(set-accidental-style 'no-reset)
c1 cis cis c
@item forget
This is sort of the opposite of @code{no-reset}: Accidentals
-are not remembered at all---and hence all accidentals are
+are not remembered at all -- and hence all accidentals are
typeset relative to the key signature, regardless of what was
before in the music
@node Setting automatic beam behavior
@subsection Setting automatic beam behavior
-@cindex @code{autoBeamSettings}
-@cindex @code{(end * * * *)}
-@cindex @code{(begin * * * *)}
+@funindex autoBeamSettings
+@funindex (end * * * *)
+@funindex (begin * * * *)
@cindex automatic beams, tuning
@cindex tuning automatic beaming
3/8 and on the fourth beat of the measure (after 3/4, that is 2 times
3/8, has passed within the measure).
+If any unexpected beam behaviour occurs, check the default automatic beam
+settings in @file{scm/@/auto@/-beam@/.scm}
+for possible interference, because the beam
+endings defined there will still apply on top of your own overrides. Any
+unwanted endings in the default vales must be reverted for your time
+signature(s).
+
+For example, to typeset @code{(3 4 3 2)}-beam endings in 12/8, begin
+with
+
+@example
+%%% revert default values in scm/auto-beam.scm regarding 12/8 time
+#(revert-auto-beam-setting '(end * * 12 8) 3 8)
+#(revert-auto-beam-setting '(end * * 12 8) 3 4)
+#(revert-auto-beam-setting '(end * * 12 8) 9 8)
+
+%%% your new values
+#(override-auto-beam-setting '(end 1 8 12 8) 3 8)
+#(override-auto-beam-setting '(end 1 8 12 8) 7 8)
+#(override-auto-beam-setting '(end 1 8 12 8) 10 8)
+@end example
+
@cindex automatic beam generation
@cindex autobeam
-@cindex @code{autoBeaming}
+@funindex autoBeaming
@cindex lyrics
If beams are used to indicate melismata in songs, then automatic
@refcommands
-@cindex @code{\autoBeamOff}
+@funindex \autoBeamOff
@code{\autoBeamOff},
-@cindex @code{\autoBeamOn}
+@funindex \autoBeamOn
@code{\autoBeamOn}.
+@commonprop
+
+Beaming patterns may be altered with the @code{beatGrouping} property,
+
+@lilypond[quote,verbatim,relative=2,fragment,ragged-right]
+\time 5/16
+\set beatGrouping = #'(2 3)
+c8[^"(2+3)" c16 c8]
+\set beatGrouping = #'(3 2)
+c8[^"(3+2)" c16 c8]
+@end lilypond
+
@refbugs
* Layout tunings within contexts::
* Changing context default settings::
* Defining new contexts::
+* Aligning contexts::
@end menu
The easiest command is @code{\new}, and it also the quickest to type.
It is prepended to a music expression, for example
-@cindex @code{\new}
+@funindex \new
@cindex new contexts
@cindex Context, creating
context already earlier with the same name.
-@cindex @code{\context}
+@funindex \context
@item
Like @code{\new}, the @code{\context} command also directs a music
@code{\context}, it is usually applied to @context{Voice}
@example
-\applyOutput #@var{function} % apply to Voice
+\applyOutput #'@var{context} #@var{function} % apply to Voice
@end example
To have it interpreted at the @context{Score} or @context{Staff} level use
these forms
@example
-\context Score \applyOutput #@var{function}
-\context Staff \applyOutput #@var{function}
+\applyOutput #'Score #@var{function}
+\applyOutput #'Staff #@var{function}
@end example
@end itemize
@subsection Changing context properties on the fly
@cindex properties
-@cindex @code{\set}
+@funindex \set
@cindex changing properties
Each context can have different @emph{properties}, variables contained
Contexts are hierarchical, so if a bigger context was specified, for
example @context{Staff}, then the change would also apply to all
@context{Voice}s in the current stave. The change is applied
-`on-the-fly', during the music, so that the setting only affects the
+@q{on-the-fly}, during the music, so that the setting only affects the
second group of eighth notes.
-@cindex @code{\unset}
+@funindex \unset
There is also an @code{\unset} command,
@example
Notation contexts (like @code{Score} and @code{Staff}) not only
store properties,
-they also contain plug-ins called ``engravers'' that create notation
+they also contain plug-ins called @q{engravers} that create notation
elements. For example, the @code{Voice} context contains a
@code{Note_head_engraver} and the @code{Staff} context contains a
@code{Key_signature_engraver}.
starting a new context with @code{\new} or @code{\context}, and
modifying it,
-@cindex @code{\with}
+@funindex \with
@example
\new @var{context} \with @{
Here @var{name} is the name of a graphical object, like @code{Stem} or
@code{NoteHead}, and @var{property} is an internal variable of the
-formatting system (`grob property' or `layout property'). The latter is a
+formatting system (@q{grob property} or @q{layout property}). The latter is a
symbol, so it must be quoted. The subsection @ref{Constructing a
tweak} explains what to fill in for @var{name}, @var{property}, and
@var{value}. Here we only discuss the functionality of this command.
\revert Staff.Stem #'thickness
@end example
-Some tweakable options are called ``subproperties'' and reside inside
+Some tweakable options are called @q{subproperties} and reside inside
properties. To tweak those, use commands of the form
@c leave this as a long long
@}
@end example
-@cindex @code{\accepts}
+@funindex \accepts
Contexts form hierarchies. We want to hang the @context{ImproVoice}
under @context{Staff}, just like normal @code{Voice}s. Therefore, we
modify the @code{Staff} definition with the @code{\accepts}
@}
@end example
-@cindex @code{\denies}
+@funindex \denies
The opposite of @code{\accepts} is @code{\denies},
which is sometimes needed when reusing existing context definitions.
@end example
+@node Aligning contexts
+@subsection Aligning contexts
+
+New contexts may be aligned above or below exisiting contexts. This
+could be useful in setting up a vocal staff (@ref{Vocal ensembles}) and
+in ossia,
+
+@cindex ossia
+@findex alignAboveContext
+@findex alignBelowContext
+
+@lilypond[quote,ragged-right]
+ossia = { f4 f f f }
+\score{
+ \relative c' \new Staff = "main" {
+ c4 c c c
+ <<
+ \new Staff \with {alignAboveContext=main} \ossia
+ { d8 f d f d f d f }
+ >>
+ }
+}
+@end lilypond
+
@node The \override command
@item a sensible value: here @code{3.0}.
@end itemize
-Some tweakable options are called ``subproperties'' and reside inside
+Some tweakable options are called @q{subproperties} and reside inside
properties. To tweak those, use commands in the form
@example
@cindex finding graphical objects
@cindex graphical object descriptions
@cindex tweaking
-@cindex @code{\override}
+@funindex \override
@cindex internal documentation
We demonstrate how to glean this information from the notation manual
@item @internalsref{Fingering}:
@internalsref{Fingering} objects are created by:
-@b{@internalsref{Fingering_engraver}}
+@internalsref{Fingering_engraver}
@item @internalsref{Fingering_engraver}:
-Music types accepted: @b{@internalsref{fingering-event}}
+Music types accepted: @internalsref{fingering-event}
@item @internalsref{fingering-event}:
Music event type @code{fingering-event} is in Music expressions named
-@b{@internalsref{FingerEvent}}
+@internalsref{FingerEvent}
@end itemize
This path goes against the flow of information in the program: it
Clicking any of the links will take you to the page of the respective
object interface. Each interface has a number of properties. Some of
-them are not user-serviceable (``Internal properties''), but others
+them are not user-serviceable (@q{Internal properties}), but others
can be modified.
We have been talking of @emph{the} @code{Fingering} object, but actually it
does not amount to much. The initialization file (see
@ref{Default files})
-@file{scm/@/define@/-grobs@/.scm} shows the soul of the `object',
+@file{scm/@/define@/-grobs@/.scm} shows the soul of the @q{object},
@example
(Fingering
the @internalsref{Fingering_engraver} plug-in says
@quotation
-Fingering_engraver is part of contexts: @dots{} @b{@internalsref{Voice}}
+Fingering_engraver is part of contexts: @dots{} @internalsref{Voice}
@end quotation
@node Objects connected to the input
@subsection Objects connected to the input
-@cindex @code{\tweak}
+@funindex \tweak
In some cases, it is possible to take a short-cut for tuning graphical
objects. For objects that result directly from a piece of the input,
There is a special type of context property: the element
description. These properties are named in @code{StudlyCaps}
(starting with capital letters). They contain the
-``default settings'' for said graphical object as an
+@q{default settings} for said graphical object as an
association list. See @file{scm/@/define@/-grobs@/.scm}
to see what kind of settings there are. Element descriptions
may be modified with @code{\override}.
The value of @code{context} (the alist) is used to initalize
the properties of individual grobs. Grobs also have
-properties, named in scheme style, with
+properties, named in Scheme style, with
@code{dashed-words}. The values of grob properties change
during the formatting process: formatting basically amounts
to computing properties using callback functions.