X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fchanging-defaults.itely;h=717384d19dc60cafd040219e45e18c436296964c;hb=9c58d562e439d8833cc8ae1d96dd65ba24fb209e;hp=e3c86964d946d761edc874349e22d914f4fcf313;hpb=9b79b0f4972f7ac809cdaddaa7c01ea549a781b4;p=lilypond.git diff --git a/Documentation/user/changing-defaults.itely b/Documentation/user/changing-defaults.itely index e3c86964d9..717384d19d 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 @@ -146,7 +154,7 @@ cis' c'' cis'2 | c'' c' @item @code{modern-cautionary} @funindex modern-cautionary -This rule is similar to @code{modern}, but the ``extra'' accidentals +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] @@ -184,7 +192,7 @@ accidentals typeset as cautionaries. @item no-reset @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 @@ -355,6 +363,28 @@ 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 @funindex autoBeaming @@ -371,6 +401,18 @@ beaming should be switched off with @code{\autoBeamOff}. @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 @@ -401,7 +444,7 @@ This section describes what contexts are, and how to modify them. @subsection Contexts explained When music is printed, a lot of notational elements must be added to the -input. For example, compare the input and output of the following example: +output. For example, compare the input and output of the following example: @lilypond[quote,verbatim,relative=2,fragment] cis4 cis2. g4 @@ -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 @@ -652,7 +695,7 @@ 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. @funindex \unset @@ -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}. @@ -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. @@ -874,8 +917,8 @@ within the current @context{Staff}. After the command is interpreted all stems are thickened. Analogous to @code{\set}, the @var{context} argument may be left out, -causing it to default to @context{Voice}, and adding @code{\once} applies -the change during one timestep only +causing the default context @context{Voice} to be used. Adding +@code{\once} applies the change during one timestep only. @lilypond[quote,fragment,verbatim,relative=2] c4 @@ -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 @@ -961,8 +1004,8 @@ from the music in the @code{\layout} block, @} @end example -Here @code{\Staff} takes the existing definition for context @context{Staff} from the -identifier @code{\Staff}. +The @code{\Staff} command brings in the existing definition of the +staff context so that it can be modified. The statements @example @@ -1057,11 +1100,10 @@ These settings are defined within a @code{\context} block inside a @} @end example -In the following discussion, the example input shown should go on the -@dots{} in the previous fragment. +In the following discussion, the example input shown should go in place +of the @dots{} in the previous fragment. -First the context's name is defined. Instead of @context{Voice} it -will be called @context{ImproVoice}, +First it is necessary to define a name for the new context: @example \name ImproVoice @@ -1075,14 +1117,15 @@ giving the new context an alias @context{Voice}, \alias Voice @end example -The context will print notes, and instructive texts +The context will print notes and instructive texts, so we need to add +the engravers which provide this functionality, @example \consists Note_heads_engraver \consists Text_engraver @end example -but only on the center line, +but we only need this on the center line, @example \consists Pitch_squash_engraver @@ -1172,15 +1215,46 @@ 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 -@section 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. +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 +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:: @@ -1188,7 +1262,8 @@ we will look in more detail at how to use the command in practice. * Layout interfaces:: * Determining the grob property:: * Objects connected to the input:: -* \set vs. \override:: +* Using Scheme code instead of \tweak:: +* \set versus \override:: * Difficult tweaks:: @end menu @@ -1204,7 +1279,7 @@ Commands which change output generally look like @end example @noindent -This means that we must determine these bits of information: +To construct this tweak we must determine these bits of information: @itemize @item the context: here @context{Voice}. @@ -1213,7 +1288,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 @@ -1227,10 +1302,17 @@ properties. To tweak those, use commands in the form @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 @@ -1291,6 +1373,14 @@ second bit of information listed under @b{See also} in the Notation manual. @end ignore +@ifnothtml +The programmer's reference is available as an HTML document. It is +highly recommended that you read it in HTML form, either online or +by downloading the HTML documentation. This section will be much more +difficult to understand if you are using the +PDF manual. +@end ifnothtml + Follow the link to @internalsref{Fingering}. At the top of the page, you will see @@ -1299,21 +1389,21 @@ Fingering objects are created by: @internalsref{Fingering_engraver} and @internalsref{New_fingering_engraver}. @end quotation -By clicking around in the program reference, we can follow the -flow of information within the program, following links like this: +By following related links inside the program reference, we can follow the +flow of information within the program: @itemize @bullet @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 @@ -1358,7 +1448,7 @@ The page for @code{Fingering} lists the definitions for the @end quotation @noindent -which means that the number will be kept at a distance of at least 0.6 +which means that the number will be kept at a distance of at least 0.5 of the note head. @@ -1402,13 +1492,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,7 +1590,7 @@ 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 @@ -1510,7 +1600,7 @@ Fingering_engraver is part of contexts: @dots{} @b{ @internalsref{Voice} } @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, +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] @@ -1522,7 +1612,7 @@ you can use the @code{\tweak} function, for example >4-\tweak #'padding #10 -. @end lilypond -As you can see, properties are set directly in the objects directly, +As you can see, properties are set in the objects directly, without mentioning the grob name or context where this should be applied. @@ -1530,8 +1620,8 @@ This technique only works for objects that are directly connected to an @internalsref{event} from the input, for example @itemize @bullet -@item note heads, caused by chord-pitch (i.e., notes inside a chord). -@item articulation signs, caused by articulation instructions. +@item note heads, caused by chord-pitch (i.e., notes inside a chord) +@item articulation signs, caused by articulation instructions @end itemize It notably does not work for stems and accidentals (these are caused @@ -1547,12 +1637,58 @@ to output, so @end example @noindent -will not change color. See @ref{Displaying music expressions} for +does not change color. See @ref{Displaying music expressions} for details. -@node \set vs. \override -@subsection \set vs. \override +@node Using Scheme code instead of \tweak +@subsection Using Scheme code instead of @code{\tweak} + +The main disadvantage of @code{\tweak} is its syntactical +inflexibility. For example, the following produces a syntax error. + +@example +F = \tweak #'font-size #-3 -\flageolet + +\relative c'' @{ + c4^\F c4_\F +@} +@end example + +@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{_}. + +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. + +@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 +@} +@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. + + +@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 @@ -1570,7 +1706,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 +1727,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.