@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:
@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{Page settings}.
+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
-@findex set-accidental-style
+@funindex set-accidental-style
@example
#(set-accidental-style 'STYLE #('CONTEXT#))
@end example
should be used instead.
@item modern
-@findex 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}
-@findex 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
-@findex 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}.
-@findex 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
-@findex 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
-@findex #(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
-@findex 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
-@findex autoBeamSettings
-@findex (end * * * *)
-@findex (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
-@findex autoBeaming
+@funindex autoBeaming
@cindex lyrics
If beams are used to indicate melismata in songs, then automatic
@refcommands
-@findex \autoBeamOff
+@funindex \autoBeamOff
@code{\autoBeamOff},
-@findex \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
-@findex \new
+@funindex \new
@cindex new contexts
@cindex Context, creating
context already earlier with the same name.
-@findex \context
+@funindex \context
@item
Like @code{\new}, the @code{\context} command also directs a music
these forms
@example
-\context \applyOutput #'Score #@var{function}
-\context \applyOutput #'Staff #@var{function}
+\applyOutput #'Score #@var{function}
+\applyOutput #'Staff #@var{function}
@end example
@end itemize
@subsection Changing context properties on the fly
@cindex properties
-@findex \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.
-@findex \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,
-@findex \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
-@findex \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
-@findex \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
-@findex \override
+@funindex \override
@cindex internal documentation
We demonstrate how to glean this information from the notation manual
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
@node Objects connected to the input
@subsection Objects connected to the input
-@findex \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.