X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fchanging-defaults.itely;h=d88bf689156c1882bc1a214a95534a4b32af40cc;hb=288a6f1c07a7f8c27991562e64e41ded621afb11;hp=a3e97c69206606956e5f183ffdd552ac14c1b6ff;hpb=3c40db4e14d2b518d370dce5af02cccc42b4fb6b;p=lilypond.git diff --git a/Documentation/user/changing-defaults.itely b/Documentation/user/changing-defaults.itely index a3e97c6920..d88bf68915 100644 --- a/Documentation/user/changing-defaults.itely +++ b/Documentation/user/changing-defaults.itely @@ -1,4 +1,12 @@ @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 @@ -6,7 +14,7 @@ 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. @@ -25,8 +33,8 @@ Program reference 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.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: @@ -46,9 +54,9 @@ Context: changing aspects of the translation from music events to 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 @@ -84,7 +92,7 @@ beams are automatically displayed. 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 @@ -132,7 +140,7 @@ used by one musician (e.g., a conductor) then 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, @@ -145,8 +153,8 @@ cis' c'' cis'2 | c'' c' @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] @@ -154,14 +162,14 @@ accidentals. They are printed in reduced size or with parentheses 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 @@ -170,21 +178,21 @@ as cautionaries. Even though all accidentals typeset by 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 @@ -192,7 +200,7 @@ 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 @@ -224,9 +232,9 @@ problematic notes. @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 @@ -355,9 +363,31 @@ In 4/4 time signature, this means that automatic beams could end only on 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 @@ -366,11 +396,23 @@ beaming should be switched off with @code{\autoBeamOff}. @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 @@ -394,6 +436,7 @@ This section describes what contexts are, and how to modify them. * Layout tunings within contexts:: * Changing context default settings:: * Defining new contexts:: +* Aligning contexts:: @end menu @@ -473,7 +516,7 @@ create them by hand. There are three commands that do this. 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 @@ -506,7 +549,7 @@ However, this user specified name is only used if there is no other context already earlier with the same name. -@cindex @code{\context} +@funindex \context @item Like @code{\new}, the @code{\context} command also directs a music @@ -585,15 +628,15 @@ several levels. For example, the @code{\applyOutput} command (see @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 @@ -603,7 +646,7 @@ these forms @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 @@ -652,10 +695,10 @@ R1*2 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 @@ -728,7 +771,7 @@ Translation @arrow{} Tunable context properties. 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}. @@ -754,7 +797,7 @@ It can be useful to shuffle around these plug-ins. This is done by starting a new context with @code{\new} or @code{\context}, and modifying it, -@cindex @code{\with} +@funindex \with @example \new @var{context} \with @{ @@ -844,7 +887,7 @@ The syntax for this is 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. @@ -910,7 +953,7 @@ affects settings that were made in the same context. In other words, the \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 @@ -1125,7 +1168,7 @@ Put together, we get @} @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} @@ -1138,7 +1181,7 @@ command, @} @end example -@cindex @code{\denies} +@funindex \denies The opposite of @code{\accepts} is @code{\denies}, which is sometimes needed when reusing existing context definitions. @@ -1172,6 +1215,30 @@ Then the output at the start of this subsection can be entered as @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 @@ -1213,7 +1280,7 @@ This means that we must determine these bits of information: @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 @@ -1224,7 +1291,7 @@ properties. To tweak those, use commands in the form @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 @@ -1306,14 +1373,14 @@ flow of information within the program, following links like this: @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 @@ -1402,13 +1469,13 @@ This object supports the following interfaces: 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 @@ -1500,14 +1567,14 @@ fact can also be deduced from the program reference, for the page for 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, @@ -1570,7 +1637,7 @@ this. Context properties are modified with @code{\set}. 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}. @@ -1591,7 +1658,7 @@ is more or less equivalent to 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.