]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/user/changing-defaults.itely
Factorize the format-metronome-markup
[lilypond.git] / Documentation / user / changing-defaults.itely
1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond.tely
3 @ignore
4     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
5
6     When revising a translation, copy the HEAD committish of the
7     version that you are working on.  See TRANSLATION for details.
8 @end ignore
9
10 @c \version "2.11.61"
11
12 @node Changing defaults
13 @chapter Changing defaults
14
15 The purpose of LilyPond's design is to provide the finest quality
16 output by default.  Nevertheless, it may happen that you need to
17 change this default layout.  The layout is controlled through a large
18 number of @q{knobs and switches} collectively called @q{properties}.
19 A tutorial introduction to accessing and modifying these properties
20 can be found in the Learning Manual, see @rlearning{Tweaking output}.
21 This should be read first.  This chapter covers similar ground, but
22 in a style more appropriate to a reference manual.
23
24 @cindex Internals Reference
25
26 The definitive description of the controls available for tuning can
27 be found in a separate document: @rinternalsnamed{Top,the Internals
28 Reference}.  That manual lists all the variables, functions and
29 options available in LilyPond.  It is written as a HTML document,
30 which is available
31 @c leave the @uref as one long line.
32 @uref{http://@/lilypond@/.org/@/doc/@/stable/@/Documentation/@/user/@/lilypond@/-internals/,on@/-line},
33 and is also included with the LilyPond documentation package.
34
35 Internally, LilyPond uses Scheme (a LISP dialect) to provide
36 infrastructure.  Overriding layout decisions in effect accesses the
37 program internals, which requires Scheme input.  Scheme elements are
38 introduced in a @code{.ly} file with the hash mark
39 @code{#}.@footnote{@rlearning{Scheme tutorial}, contains a short tutorial
40 on entering numbers, lists, strings, and symbols in Scheme.}
41
42
43 @menu
44 * Interpretation contexts::
45 * Explaining the Internals Reference::
46 * Modifying properties::
47 * Useful concepts and properties::
48 * Advanced tweaks::
49 @end menu
50
51
52 @node Interpretation contexts
53 @section Interpretation contexts
54
55 This section describes what contexts are, and how to modify them.
56
57 @menu
58 * Contexts explained::
59 * Creating contexts::
60 * Modifying context plug-ins::
61 * Changing context default settings::
62 * Defining new contexts::
63 * Aligning contexts::
64 @end menu
65
66 @seealso
67
68 Learning Manual:
69 @rlearning{Contexts and engravers}.
70
71 Installed files:
72 @file{ly/@/engraver@/-init@/.ly},
73 @file{ly/@/performer@/-init@/.ly}.
74
75 Snippets:
76 @rlsr{Contexts and engravers}.
77
78 Internals Reference:
79 @rinternals{Contexts},
80 @rinternals{Engravers and Performers}.
81
82
83 @node Contexts explained
84 @subsection Contexts explained
85
86 @ignore
87 @c TODO Rethink and rewrite
88
89 >> > > - list of contexts: my *danger unmaintainable*
90 >> > > alarm just went off.  I'm
91
92 I knew it would... And leaving out some of them is perfectly fine
93 with me.
94 I do think that a list like this, with the main contexts and a
95 brief
96 description of  what they do (perhaps also with a note about what
97 default
98 behavior is associated with each of them, but this may be
99 unmanageable),
100 should be there, and then we could simply list the remaining ones
101 without
102 further explanation and with links to the IR.
103 @end ignore
104
105 @c TODO Improve layout, order and consistency of wording -td
106
107 @c TODO Add introduction which explains contexts in generality  -td
108
109 @c TODO Describe propagation of property values -td
110
111 Contexts are arranged heirarchically:
112
113 @menu
114 * Score - the master of all contexts::
115 * Top-level contexts - staff containers::
116 * Intermediate-level contexts - staves::
117 * Bottom-level contexts - voices::
118 @end menu
119
120 @node Score - the master of all contexts
121 @unnumberedsubsubsec Score - the master of all contexts
122
123 This is the top level notation context. No other context can
124 contain a Score context. By default the Score context handles
125 the administration of time signatures and makes sure that items
126 such as clefs, time signatures, and key-signatures are aligned
127 across staves.
128
129 A Score context is instantiated implicitly when a
130 @code{\score @{@dots{}@}} or @code{\layout @{@dots{}@}} block is
131 processed, or explicitly when a @code{\new Score} command is
132 executed.
133
134 @node Top-level contexts - staff containers
135 @unnumberedsubsubsec Top-level contexts - staff containers
136
137 @strong{@emph{StaffGroup}}
138
139 Groups staves while adding a bracket on the left side, grouping
140 the staves together. The bar lines of the contained staves are
141 connected vertically. StaffGroup only consists of a collection
142 of staves, with a bracket in front and spanning bar lines.
143
144 @strong{@emph{ChoirStaff}}
145
146 Identical to StaffGroup except that the bar lines of the contained
147 staves are not connected vertically.
148
149 @strong{@emph{GrandStaff}}
150
151 A group of staves, with a brace on the left side, grouping
152 the staves together. The bar lines of the contained staves are
153 connected vertically.
154
155 @strong{@emph{PianoStaff}}
156
157 @c TODO No longer correct?  Check.  -td
158 Just like GrandStaff but with a forced distance between the
159 staves, so cross staff beaming and slurring can be used.
160
161 @ignore
162 @strong{@emph{InnerStaffGroup}}
163
164 TODO  -td
165
166 @strong{@emph{InnerChoirStaff}}
167
168 TODO  -td
169
170 @end ignore
171
172 @node Intermediate-level contexts - staves
173 @unnumberedsubsubsec Intermediate-level contexts - staves
174
175 @strong{@emph{Staff}}
176
177 Handles clefs, bar lines, keys, accidentals. It can contain
178 Voice contexts.
179
180 @strong{@emph{RhythmicStaff}}
181
182 Like Staff but for printing rhythms. Pitches are ignored;
183 the notes are printed on one line.
184
185 @strong{@emph{TabStaff}}
186
187 Context for generating tablature. By default lays the music
188 expression out as a guitar tablature, printed on six lines.
189
190 @strong{@emph{DrumStaff}}
191
192 Handles typesetting for percussion. Can contain DrumVoice
193
194 @strong{@emph{VaticanaStaff}}
195
196 Same as Staff, except that it is designed for typesetting
197 a piece in gregorian style.
198
199 @strong{@emph{MensuralStaff}}
200
201 Same as Staff, except that it is designed for typesetting
202 a piece in mensural style.
203
204 @node Bottom-level contexts - voices
205 @unnumberedsubsubsec Bottom-level contexts - voices
206
207 Voice-level contexts initialise certain properties and start
208 appropriate engravers.  Being bottom-level contexts, they cannot
209 contain other contexts.
210
211 @strong{@emph{Voice}}
212
213 Corresponds to a voice on a staff. This context handles the
214 conversion of dynamic signs, stems, beams, super- and sub-scripts,
215 slurs, ties, and rests.  You have to instantiate this explicitly
216 if you require multiple voices on the same staff.
217
218 @strong{@emph{VaticanaVoice}}
219
220 Same as Voice, except that it is designed for typesetting a piece
221 in gregorian style.
222
223 @strong{@emph{MensuralVoice}}
224
225 Same as Voice, with modifications for typesetting a piece in
226 mensural style.
227
228 @strong{@emph{Lyrics}}
229
230 Corresponds to a voice with lyrics. Handles the printing of a
231 single line of lyrics.
232
233 @strong{@emph{DrumVoice}}
234
235 The voice context used in a percussion staff.
236
237 @strong{@emph{FiguredBass}}
238
239 The context in which BassFigure objects are created from
240 input entered in @code{\figuremode} mode.
241
242 @strong{@emph{TabVoice}}
243
244 The voice context used within a TabStaff context.  Usually left to
245 be created implicitly.
246
247 @strong{@emph{ChordNames}}
248
249 Typesets chord names.
250
251 @ignore
252 TODO
253
254 Then the following, which I don't know what to do with:
255
256     * GregorianTranscriptionVoice
257     * GregorianTranscriptionStaff
258
259     * FretBoards
260         Engraves fretboards from chords. Not easy... Not
261 documented.
262         There is now some documentation on FretBoards in the NR, under
263          instrument-specific notation -- cds.
264
265     * NoteNames
266
267     * CueVoice Not documented
268     * Global
269         Hard coded entry point for LilyPond. Cannot be tuned.
270     * Devnull
271         Silently discards all musical information given to this
272 context.
273
274 @end ignore
275
276 @node Creating contexts
277 @subsection Creating contexts
278
279 @c TODO \new Score and \score
280 @c TODO more complete descriptions rather than learning style
281
282 For scores with only one voice and one staff, contexts are
283 created automatically.  For more complex scores, it is necessary to
284 create them by hand.  There are three commands that do this.
285
286 @itemize
287
288 @item
289 The easiest command is @code{\new}, and it also the quickest to type.
290 It is prepended to a music expression, for example
291
292 @funindex \new
293 @cindex new contexts
294 @cindex Context, creating
295
296 @example
297 \new @var{type} @var{music expression}
298 @end example
299
300 @noindent
301 where @var{type} is a context name (like @code{Staff} or
302 @code{Voice}).  This command creates a new context, and starts
303 interpreting the @var{music expression} with that.
304
305 A practical application of @code{\new} is a score with many
306 staves.  Each part that should be on its own staff, is preceded with
307 @code{\new Staff}.
308
309 @lilypond[quote,verbatim,relative=2,ragged-right,fragment]
310 <<
311   \new Staff { c4 c }
312   \new Staff { d4 d }
313 >>
314 @end lilypond
315
316 The @code{\new} command may also give a name to the context,
317
318 @example
319 \new @var{type} = @var{id} @var{music}
320 @end example
321 However, this user specified name is only used if there is no other
322 context already earlier with the same name.
323
324
325 @funindex \context
326
327 @item
328 Like @code{\new}, the @code{\context} command also directs a music
329 expression to a context object, but gives the context an explicit name.  The
330 syntax is
331
332 @example
333 \context @var{type} = @var{id} @var{music}
334 @end example
335
336 This form will search for an existing context of type @var{type}
337 called @var{id}.  If that context does not exist yet, a new
338 context with the specified name is created.  This is useful if
339 the context is referred to later on.  For example, when
340 setting lyrics the melody is in a named context
341
342 @example
343 \context Voice = "@b{tenor}" @var{music}
344 @end example
345
346 @noindent
347 so the texts can be properly aligned to its notes,
348
349 @example
350 \new Lyrics \lyricsto "@b{tenor}" @var{lyrics}
351 @end example
352
353 @noindent
354
355 Another possible use of named contexts is funneling two different
356 music expressions into one context.  In the following example,
357 articulations and notes are entered separately,
358
359 @example
360 music = @{ c4 c4 @}
361 arts = @{ s4-. s4-> @}
362 @end example
363
364 They are combined by sending both to the same @code{Voice} context,
365
366 @example
367 <<
368   \new Staff \context Voice = "A" \music
369   \context Voice = "A" \arts
370 >>
371 @end example
372 @lilypond[quote,ragged-right]
373 music = { c4 c4 }
374 arts = { s4-. s4-> }
375 \relative c'' <<
376   \new Staff \context Voice = "A" \music
377   \context Voice = "A" \arts
378 >>
379 @end lilypond
380
381 With this mechanism, it is possible to define an Urtext (original
382 edition), with the option to put several distinct articulations on the
383 same notes.
384
385 @cindex creating contexts
386
387 @item
388 The third command for creating contexts is
389 @example
390 \context @var{type} @var{music}
391 @end example
392
393
394 @noindent
395 This is similar to @code{\context} with @code{= @var{id}}, but matches
396 any context of type @var{type}, regardless of its given name.
397
398 This variant is used with music expressions that can be interpreted at
399 several levels.  For example, the @code{\applyOutput} command (see
400 @ref{Running a function on all layout objects}).  Without an explicit
401 @code{\context}, it is usually applied to @code{Voice}
402
403 @example
404 \applyOutput #'@var{context} #@var{function}   % apply to Voice
405 @end example
406
407 To have it interpreted at the @code{Score} or @code{Staff} level use
408 these forms
409
410 @example
411 \applyOutput #'Score #@var{function}
412 \applyOutput #'Staff #@var{function}
413 @end example
414
415 @end itemize
416
417
418 @node Modifying context plug-ins
419 @subsection Modifying context plug-ins
420
421 @c TODO Should this be Modifying engravers or Modifying contexts?
422
423 Notation contexts (like @code{Score} and @code{Staff}) not only
424 store properties,
425 they also contain plug-ins called @q{engravers} that create notation
426 elements.  For example, the @code{Voice} context contains a
427 @code{Note_head_engraver} and the @code{Staff} context contains a
428 @code{Key_signature_engraver}.
429
430 For a full a description of each plug-in, see
431 @ifhtml
432 @rinternals{Engravers and Performers}.
433 @end ifhtml
434 @ifnothtml
435 Internals Reference @expansion{} Translation @expansion{} Engravers.
436 @end ifnothtml
437 Every context described in
438 @ifhtml
439 @rinternals{Contexts}
440 @end ifhtml
441 @ifnothtml
442 Internals Reference @expansion{} Translation @expansion{} Context.
443 @end ifnothtml
444 lists the engravers used for that context.
445
446
447 It can be useful to shuffle around these plug-ins.  This is done by
448 starting a new context with @code{\new} or @code{\context}, and
449 modifying it,
450
451 @funindex \with
452
453 @example
454 \new @var{context} \with @{
455   \consists @dots{}
456   \consists @dots{}
457   \remove @dots{}
458   \remove @dots{}
459   @emph{etc.}
460 @}
461 @{
462   @emph{..music..}
463 @}
464 @end example
465
466 @noindent
467 where the @dots{} should be the name of an engraver.  Here is a simple
468 example which removes @code{Time_signature_engraver} and
469 @code{Clef_engraver} from a @code{Staff} context,
470
471 @lilypond[quote,relative=1,verbatim,fragment]
472 <<
473   \new Staff {
474     f2 g
475   }
476   \new Staff \with {
477      \remove "Time_signature_engraver"
478      \remove "Clef_engraver"
479   } {
480     f2 g2
481   }
482 >>
483 @end lilypond
484
485 In the second staff there are no time signature or clef symbols.  This
486 is a rather crude method of making objects disappear since it will affect
487 the entire staff.  This method also influences the spacing, which may or
488 may not be desirable.  More sophisticated methods of blanking objects
489 are shown in @rlearning{Visibility and color of objects}.
490
491 The next example shows a practical application.  Bar lines and time
492 signatures are normally synchronized across the score.  This is done
493 by the @code{Timing_translator} and @code{Default_bar_line_engraver}.
494 This plug-in keeps an administration of time signature, location
495 within the measure, etc.  By moving these engraver from @code{Score} to
496 @code{Staff} context, we can have a score where each staff has its own
497 time signature.
498
499 @cindex polymetric scores
500 @cindex Time signatures, multiple
501
502 @lilypond[quote,relative=1,ragged-right,verbatim,fragment]
503 \new Score \with {
504   \remove "Timing_translator"
505   \remove "Default_bar_line_engraver"
506 } <<
507   \new Staff \with {
508     \consists "Timing_translator"
509     \consists "Default_bar_line_engraver"
510   } {
511       \time 3/4
512       c4 c c c c c
513   }
514   \new Staff \with {
515     \consists "Timing_translator"
516     \consists "Default_bar_line_engraver"
517   } {
518        \time 2/4
519        c4 c c c c c
520   }
521 >>
522 @end lilypond
523
524 @knownissues
525
526 Usually the order in which the engravers are specified
527 does not matter, but in a few special cases the order
528 is important, for example where one engraver writes
529 a property and another reads it, or where one engraver
530 creates a grob and another must process it.  The order in
531 which the engravers are specified is the order in which
532 they are called to carry out their processing.
533
534 The following orderings are important: the
535 @code{Bar_engraver} must normally be first, and
536 the @code{New_fingering_engraver} must come before
537 the @code{Script_column_engraver}.  There may be others
538 with ordering dependencies.
539
540 @node Changing context default settings
541 @subsection Changing context default settings
542
543 The context settings which are to be used by default in
544 @code{Score}, @code{Staff} and @code{Voice} contexts may be specified
545 in a @code{\layout} block, as illustrated in the following example.
546 The @code{\layout} block should be placed within the @code{\score}
547 block to which it is to apply, but outside any music.
548
549 Note that the @code{\set} command itself and the context must be
550 omitted when the context default values are specified in this way:
551
552 @lilypond[quote,verbatim]
553 \score {
554   \relative c'' {
555     a4^"Really small, thicker stems, no time signature" a a a
556     a a a a
557   }
558   \layout {
559     \context {
560       \Staff
561       fontSize = #-4
562       \override Stem #'thickness = #4.0
563       \remove "Time_signature_engraver"
564     }
565   }
566 }
567 @end lilypond
568
569 In this example, the @code{\Staff} command specifies that the
570 subsequent specifications are to be applied to all staves within
571 this score block.
572
573 Modifications can be made to the @code{Score} context or all
574 @code{Voice} contexts in a similar way.
575
576 @knownissues
577
578 It is not possible to collect context changes in a variable and apply
579 them to a @code{\context} definition by referring to that variable.
580
581 The @code{\RemoveEmptyStaffContext} will overwrite your current
582 @code{\Staff} settings.  If you wish to change the defaults for a
583 staff which uses @code{\RemoveEmptyStaffContext}, you must do so
584 after calling @code{\RemoveEmptyStaffContext}, ie
585
586 @example
587 \layout @{
588   \context @{
589     \RemoveEmptyStaffContext
590
591     \override Stem #'thickness = #4.0
592   @}
593 @}
594 @end example
595
596 @c TODO: add \with in here.
597
598
599
600 @node Defining new contexts
601 @subsection Defining new contexts
602
603 Specific contexts, like @code{Staff} and @code{Voice}, are made of
604 simple building blocks.  It is possible to create new types of
605 contexts with different combinations of engraver plug-ins.
606
607 The next example shows how to build a different type of
608 @code{Voice} context from scratch.  It will be similar to
609 @code{Voice}, but only prints centered slash note heads.  It can be used
610 to indicate improvisation in jazz pieces,
611
612 @lilypond[quote,ragged-right]
613 \layout { \context {
614   \name ImproVoice
615   \type "Engraver_group"
616   \consists "Note_heads_engraver"
617   \consists "Text_engraver"
618   \consists Pitch_squash_engraver
619   squashedPosition = #0
620   \override NoteHead #'style = #'slash
621   \override Stem #'transparent = ##t
622   \alias Voice
623 }
624 \context { \Staff
625   \accepts "ImproVoice"
626 }}
627
628 \relative c'' {
629   a4 d8 bes8 \new ImproVoice { c4^"ad lib" c
630    c4 c^"undress" c_"while playing :)" c }
631   a1
632 }
633 @end lilypond
634
635
636 These settings are defined within a @code{\context} block inside a
637 @code{\layout} block,
638
639 @example
640 \layout @{
641   \context @{
642     @dots{}
643   @}
644 @}
645 @end example
646
647 In the following discussion, the example input shown should go in place
648 of the @dots{} in the previous fragment.
649
650 First it is necessary to define a name for the new context:
651
652 @example
653 \name ImproVoice
654 @end example
655
656 Since it is similar to the @code{Voice}, we want commands that work
657 on (existing) @code{Voice}s to remain working.  This is achieved by
658 giving the new context an alias @code{Voice},
659
660 @example
661 \alias Voice
662 @end example
663
664 The context will print notes and instructive texts, so we need to add
665 the engravers which provide this functionality,
666
667 @example
668 \consists Note_heads_engraver
669 \consists Text_engraver
670 @end example
671
672 but we only need this on the center line,
673
674 @example
675 \consists Pitch_squash_engraver
676 squashedPosition = #0
677 @end example
678
679 The @rinternals{Pitch_squash_engraver} modifies note heads (created
680 by @rinternals{Note_heads_engraver}) and sets their vertical
681 position to the value of @code{squashedPosition}, in this case@tie{}@code{0},
682 the center line.
683
684 The notes look like a slash, and have no stem,
685
686 @example
687 \override NoteHead #'style = #'slash
688 \override Stem #'transparent = ##t
689 @end example
690
691 All these plug-ins have to cooperate, and this is achieved with a
692 special plug-in, which must be marked with the keyword @code{\type}.
693 This should always be @code{Engraver_group}.
694
695 @example
696 \type "Engraver_group"
697 @end example
698
699 Put together, we get
700
701 @example
702 \context @{
703   \name ImproVoice
704   \type "Engraver_group"
705   \consists "Note_heads_engraver"
706   \consists "Text_engraver"
707   \consists Pitch_squash_engraver
708   squashedPosition = #0
709   \override NoteHead #'style = #'slash
710   \override Stem #'transparent = ##t
711   \alias Voice
712 @}
713 @end example
714
715 @funindex \accepts
716 Contexts form hierarchies.  We want to hang the @code{ImproVoice}
717 under @code{Staff}, just like normal @code{Voice}s.  Therefore, we
718 modify the @code{Staff} definition with the @code{\accepts}
719 command,
720
721 @example
722 \context @{
723   \Staff
724   \accepts ImproVoice
725 @}
726 @end example
727
728 @funindex \denies
729 The opposite of @code{\accepts} is @code{\denies},
730 which is sometimes needed when reusing existing context definitions.
731
732 Putting both into a @code{\layout} block, like
733
734 @example
735 \layout @{
736   \context @{
737     \name ImproVoice
738     @dots{}
739   @}
740   \context @{
741     \Staff
742     \accepts "ImproVoice"
743   @}
744 @}
745 @end example
746
747 Then the output at the start of this subsection can be entered as
748
749 @example
750 \relative c'' @{
751   a4 d8 bes8
752   \new ImproVoice @{
753     c4^"ad lib" c
754     c4 c^"undress"
755     c c_"while playing :)"
756   @}
757   a1
758 @}
759 @end example
760
761
762 @node Aligning contexts
763 @subsection Aligning contexts
764
765 New contexts may be aligned above or below existing contexts.  This
766 could be useful in setting up a vocal staff (@rlearning{Vocal ensembles}) and
767 in ossia,
768
769 @c TODO Better example needed.  Ref LM, and expand on it.
770
771 @cindex ossia
772 @funindex alignAboveContext
773 @funindex alignBelowContext
774
775 @lilypond[quote,ragged-right]
776 ossia = { f4 f f f }
777 \score{
778   \relative c' \new Staff = "main" {
779     c4 c c c
780     <<
781       \new Staff \with {alignAboveContext=main} \ossia
782       { d8 f d f d f d f }
783     >>
784   }
785 }
786 @end lilypond
787
788 @cindex nested contexts
789 @cindex contexts, nested
790
791 @funindex \accepts
792 @funindex \denies
793
794 Contexts like @code{PianoStaff} can contain other contexts
795 nested within them.  Contexts which are acceptable for nesting
796 are defined by the @qq{accepts} list of a context.  Contexts
797 which are not in this list are placed below the outer context
798 in the printed score.
799 For example, the @code{PianoStaff} context is defined by default
800 to accept @code{Staff} and @code{FiguredBass} contexts within
801 it, but not (for example) a @code{Lyrics} context.  So in the
802 following structure the lyrics are placed below the piano staff
803 rather than between the two staves:
804
805 @lilypond[verbatim,quote,relative=1]
806 \new PianoStaff
807 <<
808   \new Staff { e4 d c2 }
809   \addlyrics { Three blind mice }
810   \new Staff {
811     \clef "bass"
812     { c,1 }
813   }
814 >>
815 @end lilypond
816
817 The @qq{accepts} list of a context can be modified to include
818 additional nested contexts, so if we wanted the lyrics to appear
819 between the two staves we could use:
820
821 @lilypond[verbatim,quote,relative=1]
822 \new PianoStaff \with { \accepts Lyrics }
823 <<
824   \new Staff { e4 d c2 }
825   \addlyrics { Three blind mice }
826   \new Staff {
827     \clef "bass"
828     { c,1 }
829   }
830 >>
831 @end lilypond
832
833 The opposite of @code{\accepts} is @code{\denies}; this removes a
834 context from the @qq{accepts} list.
835
836 @node Explaining the Internals Reference
837 @section Explaining the Internals Reference
838
839
840 @menu
841 * Navigating the program reference::
842 * Layout interfaces::
843 * Determining the grob property::
844 * Naming conventions::
845 @end menu
846
847 @node Navigating the program reference
848 @subsection Navigating the program reference
849
850 @c TODO remove this (it's in the LM)
851 @c Replace with more factual directions
852
853 Suppose we want to move the fingering indication in the fragment
854 below:
855
856 @lilypond[quote,fragment,relative=2,verbatim]
857 c-2
858 \stemUp
859 f
860 @end lilypond
861
862 If you visit the documentation on fingering instructions (in
863 @ref{Fingering instructions}), you will notice:
864
865 @quotation
866 @strong{See also}
867
868 Internals Reference: @rinternals{Fingering}.
869
870 @end quotation
871
872
873 @c  outdated info; probably will delete.
874 @ignore
875 This fragment points to two parts of the program reference: a page
876 on @code{FingeringEvent} and one on @code{Fingering}.
877
878 The page on @code{FingeringEvent} describes the properties of the music
879 expression for the input @code{-2}.  The page contains many links
880 forward.  For example, it says
881
882 @quotation
883 Accepted by: @rinternals{Fingering_engraver},
884 @end quotation
885
886 @noindent
887 That link brings us to the documentation for the Engraver, the
888 plug-in, which says
889
890 @quotation
891 This engraver creates the following layout objects: @rinternals{Fingering}.
892 @end quotation
893
894 In other words, once the @code{FingeringEvent}s are interpreted, the
895 @code{Fingering_engraver} plug-in will process them.
896 @end ignore
897
898 @ignore
899 @c  I can't figure out what this is supposed to mean.  -gp
900
901 The @code{Fingering_engraver} is also listed to create
902 @rinternals{Fingering} objects,
903
904 @c  old info?  it doesn't make any sense to me with our current docs.
905 This is also the
906 second bit of information listed under @b{See also} in the Notation
907 manual.
908 @end ignore
909
910 @ifnothtml
911 The programmer's reference is available as an HTML document.  It is
912 highly recommended that you read it in HTML form, either online or
913 by downloading the HTML documentation.  This section will be much more
914 difficult to understand if you are using the
915 PDF manual.
916 @end ifnothtml
917
918 Follow the link to @rinternals{Fingering}.  At the top of the
919 page, you will see
920
921 @quotation
922 Fingering objects are created by: @rinternals{Fingering_engraver} and
923 @rinternals{New_fingering_engraver}.
924 @end quotation
925
926 By following related links inside the program reference, we can follow the
927 flow of information within the program:
928
929 @itemize
930
931 @item @rinternals{Fingering}:
932 @rinternals{Fingering} objects are created by:
933 @rinternals{Fingering_engraver}
934
935 @item @rinternals{Fingering_engraver}:
936 Music types accepted: @rinternals{fingering-event}
937
938 @item @rinternals{fingering-event}:
939 Music event type @code{fingering-event} is in Music expressions named
940 @rinternals{FingeringEvent}
941 @end itemize
942
943 This path goes against the flow of information in the program: it
944 starts from the output, and ends at the input event.  You could
945 also start at an input event, and read with the flow of
946 information, eventually ending up at the output object(s).
947
948 The program reference can also be browsed like a normal document.  It
949 contains chapters on
950 @ifhtml
951 @rinternals{Music definitions},
952 @end ifhtml
953 @ifnothtml
954 @code{Music definitions}
955 @end ifnothtml
956 on @rinternals{Translation}, and the @rinternals{Backend}.  Every
957 chapter lists all the definitions used and all properties that may be
958 tuned.
959
960
961 @node Layout interfaces
962 @subsection Layout interfaces
963
964 @cindex interface, layout
965 @cindex layout interface
966 @cindex grob
967
968 The HTML page that we found in the previous section describes the
969 layout object called @rinternals{Fingering}.  Such an object is a
970 symbol within the score.  It has properties that store numbers (like
971 thicknesses and directions), but also pointers to related objects.  A
972 layout object is also called a @emph{Grob}, which is short for Graphical
973 Object.  For more details about Grobs, see @rinternals{grob-interface}.
974
975 The page for @code{Fingering} lists the definitions for the
976 @code{Fingering} object.  For example, the page says
977
978 @quotation
979 @code{padding} (dimension, in staff space):
980
981 @code{0.5}
982 @end quotation
983
984 @noindent
985 which means that the number will be kept at a distance of at least 0.5
986 of the note head.
987
988
989 Each layout object may have several functions as a notational or
990 typographical element.  For example, the Fingering object
991 has the following aspects
992
993 @itemize
994 @item
995 Its size is independent of the horizontal spacing, unlike slurs or beams.
996
997 @item
998 It is a piece of text.  Granted, it is usually a very short text.
999
1000 @item
1001 That piece of text is typeset with a font, unlike slurs or beams.
1002
1003 @item
1004 Horizontally, the center of the symbol should be aligned to the
1005 center of the note head.
1006
1007 @item
1008 Vertically, the symbol is placed next to the note and the staff.
1009
1010 @item
1011 The vertical position is also coordinated with other superscript
1012 and subscript symbols.
1013 @end itemize
1014
1015 Each of these aspects is captured in so-called @emph{interface}s,
1016 which are listed on the @rinternals{Fingering} page at the bottom
1017
1018 @quotation
1019 This object supports the following interfaces:
1020 @rinternals{item-interface},
1021 @rinternals{self-alignment-interface},
1022 @rinternals{side-position-interface}, @rinternals{text-interface},
1023 @rinternals{text-script-interface}, @rinternals{font-interface},
1024 @rinternals{finger-interface}, and @rinternals{grob-interface}.
1025 @end quotation
1026
1027 Clicking any of the links will take you to the page of the respective
1028 object interface.  Each interface has a number of properties.  Some of
1029 them are not user-serviceable (@q{Internal properties}), but others
1030 can be modified.
1031
1032 We have been talking of @emph{the} @code{Fingering} object, but actually it
1033 does not amount to much.  The initialization file (see
1034 @rlearning{Other sources of information})
1035 @file{scm/@/define@/-grobs@/.scm} shows the soul of the @q{object},
1036
1037 @example
1038 (Fingering
1039   . ((padding . 0.5)
1040      (avoid-slur . around)
1041      (slur-padding . 0.2)
1042      (staff-padding . 0.5)
1043      (self-alignment-X . 0)
1044      (self-alignment-Y . 0)
1045      (script-priority . 100)
1046      (stencil . ,ly:text-interface::print)
1047      (direction . ,ly:script-interface::calc-direction)
1048      (font-encoding . fetaNumber)
1049      (font-size . -5)           ; don't overlap when next to heads.
1050      (meta . ((class . Item)
1051      (interfaces . (finger-interface
1052                     font-interface
1053                     text-script-interface
1054                     text-interface
1055                     side-position-interface
1056                     self-alignment-interface
1057                     item-interface))))))
1058 @end example
1059
1060 @noindent
1061 As you can see, the @code{Fingering} object is nothing more than a
1062 bunch of variable settings, and the webpage in the Internals Reference
1063 is directly generated from this definition.
1064
1065
1066 @node Determining the grob property
1067 @subsection Determining the grob property
1068
1069 @c TODO remove this (it's in the LM)
1070 @c Replace with more factual directions
1071
1072 Recall that we wanted to change the position of the @b{2} in
1073
1074 @lilypond[quote,fragment,relative=2,verbatim]
1075 c-2
1076 \stemUp
1077 f
1078 @end lilypond
1079
1080 Since the @b{2} is vertically positioned next to its note, we have to
1081 meddle with the interface associated with this positioning.  This is
1082 done using @code{side-position-interface}.  The page for this interface
1083 says
1084
1085 @quotation
1086 @code{side-position-interface}
1087
1088 Position a victim object (this one) next to other objects (the
1089 support).  The property @code{direction} signifies where to put the
1090 victim object relative to the support (left or right, up or down?)
1091 @end quotation
1092
1093 @cindex padding
1094 @noindent
1095 Below this description, the variable @code{padding} is described as
1096
1097 @quotation
1098 @table @code
1099 @item padding
1100 (dimension, in staff space)
1101
1102 Add this much extra space between objects that are next to each other.
1103 @end table
1104 @end quotation
1105
1106 By increasing the value of @code{padding}, we can move the
1107 fingering away from the note head.  The following command inserts
1108 3 staff spaces of white
1109 between the note and the fingering:
1110 @example
1111 \once \override Voice.Fingering #'padding = #3
1112 @end example
1113
1114 Inserting this command before the Fingering object is created,
1115 i.e., before @code{c2}, yields the following result:
1116
1117 @lilypond[quote,relative=2,fragment,verbatim]
1118 \once \override Voice.Fingering #'padding = #3
1119 c-2
1120 \stemUp
1121 f
1122 @end lilypond
1123
1124
1125 In this case, the context for this tweak is @code{Voice}.  This
1126 fact can also be deduced from the program reference, for the page for
1127 the @rinternals{Fingering_engraver} plug-in says
1128
1129 @quotation
1130 Fingering_engraver is part of contexts: @dots{} @rinternals{Voice}
1131 @end quotation
1132
1133
1134 @node Naming conventions
1135 @subsection Naming conventions
1136
1137 Another thing that is needed, is an overview of the various naming
1138 conventions:
1139
1140     scheme functions: lowercase-with-hyphens (incl. one-word
1141 names)
1142     scheme functions: ly:plus-scheme-style
1143     music events, music classes and music properties:
1144 as-scheme-functions
1145     Grob interfaces: scheme-style
1146     backend properties: scheme-style (but X and Y!)
1147     contexts (and MusicExpressions and grobs): Capitalized or
1148 CamelCase
1149     context properties: lowercaseFollowedByCamelCase
1150     engravers:
1151 Capitalized_followed_by_lowercase_and_with_underscores
1152
1153 Which of these are conventions and which are rules?
1154 Which are rules of the underlying language, and which are
1155 LP-specific?
1156
1157
1158 @node Modifying properties
1159 @section Modifying properties
1160
1161 @c TODO change the menu and subsection node names to use
1162 @c backslash once the new macro to handle the refs
1163 @c is available.  Need to find and change all refs at
1164 @c the same time. -td
1165
1166 @menu
1167 * Overview of modifying properties::
1168 * The set command::
1169 * The override command::
1170 * The tweak command::
1171 * set versus override::
1172 @end menu
1173
1174
1175 @node Overview of modifying properties
1176 @subsection Overview of modifying properties
1177
1178 Each context is responsible for creating certain types of graphical
1179 objects.  The settings used for printing these objects are also stored by
1180 context.  By changing these settings, the appearance of objects can be
1181 altered.
1182
1183 The syntax for this is
1184
1185 @example
1186 \override @var{context}.@var{name} #'@var{property} = #@var{value}
1187 @end example
1188
1189 Here @var{name} is the name of a graphical object, like
1190 @code{Stem} or @code{NoteHead}, and @var{property} is an internal
1191 variable of the formatting system (@q{grob property} or @q{layout
1192 property}).  The latter is a symbol, so it must be quoted.  The
1193 subsection @ref{Modifying properties}, explains what to fill in
1194 for @var{name}, @var{property}, and @var{value}.  Here we only
1195 discuss the functionality of this command.
1196
1197 The command
1198
1199 @verbatim
1200 \override Staff.Stem #'thickness = #4.0
1201 @end verbatim
1202
1203 @noindent
1204 makes stems thicker (the default is 1.3, with staff line thickness as a
1205 unit).  Since the command specifies @code{Staff} as context, it only
1206 applies to the current staff.  Other staves will keep their normal
1207 appearance.  Here we see the command in action:
1208
1209 @lilypond[quote,verbatim,relative=2,fragment]
1210 c4
1211 \override Staff.Stem #'thickness = #4.0
1212 c4
1213 c4
1214 c4
1215 @end lilypond
1216
1217 The @code{\override} command changes the definition of the @code{Stem}
1218 within the current @code{Staff}.  After the command is interpreted
1219 all stems are thickened.
1220
1221 Analogous to @code{\set}, the @var{context} argument may be left out,
1222 causing the default context @code{Voice} to be used.  Adding
1223 @code{\once} applies the change during one timestep only.
1224
1225 @lilypond[quote,fragment,verbatim,relative=2]
1226 c4
1227 \once \override Stem #'thickness = #4.0
1228 c4
1229 c4
1230 @end lilypond
1231
1232 The @code{\override} must be done before the object is
1233 started.  Therefore, when altering @emph{Spanner} objects such as slurs
1234 or beams, the @code{\override} command must be executed at the moment
1235 when the object is created.  In this example,
1236
1237 @lilypond[quote,fragment,verbatim,relative=2]
1238 \override Slur #'thickness = #3.0
1239 c8[( c
1240 \override Beam #'thickness = #0.6
1241 c8 c])
1242 @end lilypond
1243
1244 @noindent
1245 the slur is fatter but the beam is not.  This is because the command for
1246 @code{Beam} comes after the Beam is started, so it has no effect.
1247
1248 Analogous to @code{\unset}, the @code{\revert} command for a context
1249 undoes an @code{\override} command; like with @code{\unset}, it only
1250 affects settings that were made in the same context.  In other words, the
1251 @code{\revert} in the next example does not do anything.
1252
1253 @example
1254 \override Voice.Stem #'thickness = #4.0
1255 \revert Staff.Stem #'thickness
1256 @end example
1257
1258 Some tweakable options are called @q{subproperties} and reside inside
1259 properties.  To tweak those, use commands of the form
1260
1261 @c leave this as a long long
1262 @example
1263 \override @var{context}.@var{name} #'@var{property} #'@var{subproperty} = #@var{value}
1264 @end example
1265
1266 @noindent
1267 such as
1268
1269 @example
1270 \override Stem #'details #'beamed-lengths = #'(4 4 3)
1271 @end example
1272
1273
1274 @seealso
1275
1276 Internals: @rinternals{OverrideProperty}, @rinternals{RevertProperty},
1277 @rinternals{PropertySet}, @rinternals{Backend}, and
1278 @rinternals{All layout objects}.
1279
1280
1281 @knownissues
1282
1283 The back-end is not very strict in type-checking object properties.
1284 Cyclic references in Scheme values for properties can cause hangs
1285 or crashes, or both.
1286
1287
1288
1289 @node The set command
1290 @subsection The @code{\set} command
1291
1292 @cindex properties
1293 @funindex \set
1294 @cindex changing properties
1295
1296 Each context can have different @emph{properties}, variables contained
1297 in that context.  They can be changed during the interpretation step.
1298 This is achieved by inserting the @code{\set} command in the music,
1299
1300 @example
1301 \set @var{context}.@var{prop} = #@var{value}
1302 @end example
1303
1304 For example,
1305 @lilypond[quote,verbatim,relative=2,fragment]
1306 R1*2
1307 \set Score.skipBars = ##t
1308 R1*2
1309 @end lilypond
1310
1311 This command skips measures that have no notes.  The result is that
1312 multi-rests are condensed.  The value assigned is a Scheme object.  In
1313 this case, it is @code{#t}, the boolean True value.
1314
1315 If the @var{context} argument is left out, then the current bottom-most
1316 context (typically @code{ChordNames}, @code{Voice}, or
1317 @code{Lyrics}) is used.  In this example,
1318
1319 @lilypond[quote,verbatim,relative=2,fragment]
1320 c8 c c c
1321 \set autoBeaming = ##f
1322 c8 c c c
1323 @end lilypond
1324
1325 @noindent
1326 the @var{context} argument to @code{\set} is left out, so automatic
1327 beaming is switched off in the current @rinternals{Voice}.  Note that
1328 the bottom-most context does not always contain the property that you
1329 wish to change -- for example, attempting to set the @code{skipBars}
1330 property (of the bottom-most context, in this case @code{Voice}) will
1331 have no effect.
1332
1333 @lilypond[quote,verbatim,relative=2,fragment]
1334 R1*2
1335 \set skipBars = ##t
1336 R1*2
1337 @end lilypond
1338
1339 Contexts are hierarchical, so if a bigger context was specified, for
1340 example @code{Staff}, then the change would also apply to all
1341 @code{Voice}s in the current stave.  The change is applied
1342 @q{on-the-fly}, during the music, so that the setting only affects the
1343 second group of eighth notes.
1344
1345 @funindex \unset
1346
1347 There is also an @code{\unset} command,
1348 @example
1349 \unset @var{context}.@var{prop}
1350 @end example
1351
1352 @noindent
1353 which removes the definition of @var{prop}.  This command removes
1354 the definition only if it is set in @var{context}, so
1355
1356 @example
1357 \set Staff.autoBeaming = ##f
1358 @end example
1359
1360 @noindent
1361 introduces a property setting at @code{Staff} level.  The setting also
1362 applies to the current @code{Voice}.  However,
1363
1364 @example
1365 \unset Voice.autoBeaming
1366 @end example
1367
1368 @noindent
1369 does not have any effect.  To cancel this setting, the @code{\unset}
1370 must be specified on the same level as the original @code{\set}.  In
1371 other words, undoing the effect of @code{Staff.autoBeaming = ##f}
1372 requires
1373 @example
1374 \unset Staff.autoBeaming
1375 @end example
1376
1377 Like @code{\set}, the @var{context} argument does not have to be
1378 specified for a bottom context, so the two statements
1379
1380 @example
1381 \set Voice.autoBeaming = ##t
1382 \set autoBeaming = ##t
1383 @end example
1384
1385 @noindent
1386 are equivalent.
1387
1388
1389 @cindex \once
1390 Settings that should only apply to a single time-step can be entered
1391 with @code{\once}, for example in
1392
1393 @lilypond[quote,verbatim,relative=2,fragment]
1394 c4
1395 \once \set fontSize = #4.7
1396 c4
1397 c4
1398 @end lilypond
1399
1400 the property @code{fontSize} is unset automatically after the second
1401 note.
1402
1403 A full description of all available context properties is in the
1404 program reference, see
1405 @ifhtml
1406 @rinternals{Tunable context properties}.
1407 @end ifhtml
1408 @ifnothtml
1409 Translation @expansion{} Tunable context properties.
1410 @end ifnothtml
1411
1412
1413
1414 @node The override command
1415 @subsection The @code{\override} command
1416
1417 Commands which change output generally look like
1418
1419 @example
1420 \override Voice.Stem #'thickness = #3.0
1421 @end example
1422
1423 @noindent
1424 To construct this tweak we must determine these bits of information:
1425
1426 @itemize
1427 @item the context: here @code{Voice}.
1428 @item the layout object: here @code{Stem}.
1429 @item the layout property: here @code{thickness}.
1430 @item a sensible value: here @code{3.0}.
1431 @end itemize
1432
1433 Some tweakable options are called @q{subproperties} and reside inside
1434 properties.  To tweak those, use commands in the form
1435
1436 @example
1437 \override Stem #'details #'beamed-lengths = #'(4 4 3)
1438 @end example
1439
1440 @cindex internal documentation
1441 @cindex finding graphical objects
1442 @cindex graphical object descriptions
1443 @cindex tweaking
1444 @funindex \override
1445 @cindex internal documentation
1446
1447 For many properties, regardless of the data type of the property, setting the
1448 property to false ( @code{##f} ) will result in turning it off, causing
1449 LilyPond to ignore that property entirely.  This is particularly useful for
1450 turning off grob properties which may otherwise be causing problems.
1451
1452 We demonstrate how to glean this information from the notation manual
1453 and the program reference.
1454
1455
1456 @node The tweak command
1457 @subsection The @code{\tweak} command
1458
1459 @funindex \tweak
1460 @cindex tweaking
1461
1462 In some cases, it is possible to take a short-cut for tuning
1463 graphical objects.  For objects that are created directly from
1464 an item in the input file, you can use the @code{\tweak} command.
1465 For example:
1466
1467 @lilypond[relative=2,verbatim]
1468 < c
1469   \tweak #'color #red
1470   d
1471   g
1472   \tweak #'duration-log #1
1473   a
1474 > 4
1475 -\tweak #'padding #8
1476 -^
1477 @end lilypond
1478
1479 @cindex chord, modifying one note in
1480
1481 But the main use of the @code{\tweak} command is to modify just
1482 one of a number of notation elements which start at the same musical
1483 moment, like the notes of a chord, or tuplet brackets which start
1484 at the same time.
1485
1486 For an introduction to the syntax and uses of the tweak command
1487 see @rlearning{Tweaking methods}.
1488
1489 The @code{\tweak} command sets a property in the following object
1490 directly, without requiring the grob name or context to be
1491 specified.  For this to work, it is necessary for the @code{\tweak}
1492 command to remain immediately adjacent to the object to which it is
1493 to apply after the input file has been converted to a music stream.
1494 This is often not the case, as many additional elements are inserted
1495 into the music stream implicitly.  For example, when a note which is
1496 not part of a chord is processed, Lilypond implicitly inserts a
1497 @code{ChordEvent} event before the note, so separating the tweak
1498 from the note.  However, if chord symbols are placed round the
1499 tweak and the note, the @code{\tweak} command comes after the
1500 @code{ChordEvent} in the music stream, so remaining adjacent to the
1501 note, and able to modify it.
1502
1503 So, this works:
1504
1505 @lilypond[relative=2,verbatim,quote]
1506 <\tweak #'color #red c>4
1507 @end lilypond
1508
1509 @noindent
1510 but this does not:
1511
1512 @lilypond[relative=2,verbatim,quote]
1513 \tweak #'color #red c4
1514 @end lilypond
1515
1516 When several similar items are placed at the same musical moment,
1517 the @code{\override} command cannot be used to modify just one of
1518 them -- this is where the @code{\tweak} command must be used.
1519 Items which may appear more than once at the same musical moment
1520 include the following:
1521
1522 @c TODO expand to include any further uses of \tweak
1523 @itemize
1524 @item note heads of notes inside a chord
1525 @item articulation signs on a single note
1526 @item ties between notes in a chord
1527 @item tuplet brackets starting at the same time
1528 @end itemize
1529
1530 @c TODO add examples of these
1531
1532 @noindent
1533 and @code{\tweak} may be used to modify any single occurrence of
1534 these items.
1535
1536 Notably the @code{\tweak} command cannot be used to modify stems,
1537 beams or accidentals, since these are generated later by note heads,
1538 rather than by music elements in the input stream.  Nor can a
1539 @code{\tweak} command be used to modify clefs or time signatures,
1540 since these become separated from any preceding @code{\tweak}
1541 command in the input stream by the automatic insertion of extra
1542 elements required to specify the context.
1543
1544 But the @code{\tweak} command can be used as an alternative to
1545 the @code{\override} command to modify those notational elements
1546 that do not cause any additional implicit elements to be added
1547 before them in the music stream.  For example, slurs may be
1548 modified in this way:
1549
1550 @lilypond[verbatim,quote,relative=1]
1551 c-\tweak #'thickness #5 ( d e f)
1552 @end lilypond
1553
1554 Also several @code{\tweak} commands may be placed before a
1555 notational element -- all affect it:
1556
1557 @lilypond[verbatim,quote,relative=1]
1558 c
1559 -\tweak #'style #'dashed-line
1560 -\tweak #'dash-fraction #0.2
1561 -\tweak #'thickness #3
1562 -\tweak #'color #red
1563  \glissando
1564 f'
1565 @end lilypond
1566
1567 The music stream which is generated from a section of an input file,
1568 including any automatically inserted elements, may be examined,
1569 see @ref{Displaying music expressions}.  This may be helpful in
1570 determining what may be modified by a @code{\tweak} command.
1571
1572 @seealso
1573
1574 Learning Manual:
1575 @rlearning{Tweaking methods}.
1576
1577 Notation Reference:
1578 @ref{Displaying music expressions}.
1579
1580 @knownissues
1581
1582 @cindex tweaks in a variable
1583 The @code{\tweak} command cannot be used inside a variable.
1584
1585 @cindex tweaks in lyrics
1586 The @code{\tweak} commands cannot be used in @code{\lyricmode}.
1587
1588 @cindex tweaking control points
1589 @cindex control points, tweaking
1590
1591 The @code{\tweak} command cannot be used to modify the control
1592 points of just one of several ties in a chord, other than the first
1593 one encountered in the input file.
1594
1595 @node set versus override
1596 @subsection @code{\set} vs. @code{\override}
1597
1598 We have seen two methods of changing properties: @code{\set} and
1599 @code{\override}.  There are actually two different kinds of
1600 properties.
1601
1602 Contexts can have properties, which are usually named in
1603 @code{studlyCaps}.  They mostly control the translation from
1604 music to notation, eg. @code{localKeySignature} (for determining
1605 whether to print accidentals), @code{measurePosition} (for
1606 determining when to print a bar line).  Context properties can
1607 change value over time while interpreting a piece of music;
1608 @code{measurePosition} is an obvious example of
1609 this.  Context properties are modified with @code{\set}.
1610
1611 There is a special type of context property: the element
1612 description.  These properties are named in @code{StudlyCaps}
1613 (starting with capital letters).  They contain the
1614 @q{default settings} for said graphical object as an
1615 association list.  See @file{scm/@/define@/-grobs@/.scm}
1616 to see what kind of settings there are.  Element descriptions
1617 may be modified with @code{\override}.
1618
1619 @code{\override} is actually a shorthand;
1620
1621 @example
1622 \override @var{context}.@var{name} #'@var{property} = #@var{value}
1623 @end example
1624
1625 @noindent
1626 is more or less equivalent to
1627
1628 @c  leave this long line -gp
1629 @example
1630 \set @var{context}.@var{name} #'@var{property} = #(cons (cons '@var{property} @var{value}) <previous value of @var{context})
1631 @end example
1632
1633 The value of @code{context} (the alist) is used to initialize
1634 the properties of individual grobs.  Grobs also have
1635 properties, named in Scheme style, with
1636 @code{dashed-words}.  The values of grob properties change
1637 during the formatting process: formatting basically amounts
1638 to computing properties using callback functions.
1639
1640 @code{fontSize} is a special property: it is equivalent to
1641 entering @code{\override ... #'font-size} for all pertinent
1642 objects.  Since this is a common change, the special
1643 property (modified with @code{\set}) was created.
1644
1645
1646 @node Useful concepts and properties
1647 @section Useful concepts and properties
1648
1649
1650 @menu
1651 * Input modes::
1652 * Direction and placement::
1653 * Distances and measurements::
1654 * Staff symbol properties::
1655 * Spanners::
1656 * Visibility of objects::
1657 * Line styles::
1658 * Rotating objects::
1659 @end menu
1660
1661 @node Input modes
1662 @subsection Input modes
1663
1664 The way in which the notation contained within an input file is
1665 interpreted is determined by the current input mode.
1666
1667 @strong{Chord mode}
1668
1669 This is activated with the @code{\chordmode} command, and causes
1670 input to be interpreted with the syntax of chord notation, see
1671 @ref{Chord notation}.  Chords are rendered as notes on a staff.
1672
1673 Chord mode is also activated with the @code{\chords} command.
1674 This also creates a new @code{ChordNames} context and
1675 causes the following input to be interpreted with the syntax of
1676 chord notation and rendered as chord names in the @code{ChordNames}
1677 context, see @ref{Printing chord names}.
1678
1679 @strong{Drum mode}
1680
1681 This is activated with the @code{\drummode} command, and causes
1682 input to be interpreted with the syntax of drum notation, see
1683 @ref{Basic percussion notation}.
1684
1685 Drum mode is also activated with the @code{\drums} command.
1686 This also creates a new @code{DrumStaff} context and causes the
1687 following input to be interpreted with the syntax of drum notation
1688 and rendered as drum symbols on a drum staff, see @ref{Basic
1689 percussion notation}.
1690
1691 @strong{Figure mode}
1692
1693 This is activated with the @code{\figuremode} command, and causes
1694 input to be interpreted with the syntax of figured bass, see
1695 @ref{Entering figured bass}.
1696
1697 Figure mode is also activated with the @code{\figures} command.
1698 This also creates a new @code{FiguredBass} context and causes the
1699 following input to be interpreted with the figured bass syntax
1700 and rendered as figured bass symbols in the @code{FiguredBass}
1701 context, see @ref{Introduction to figured bass}.
1702
1703 @strong{Fret and tab modes}
1704
1705 There are no special input modes for entering fret and tab symbols.
1706
1707 To create tab diagrams, enter notes or chords in note mode and
1708 render them in a @code{TabStaff} context, see
1709 @ref{Default tablatures}.
1710
1711 To create fret diagrams above a staff, you have two choices.
1712 You can either use the @code{FretBoards} context (see
1713 @ref{Automatic fret diagrams} or you can enter them as a markup
1714 above the notes using the @code{\fret-diagram} command (see
1715 @ref{Fret diagram markups}).
1716
1717 @strong{Lyrics mode}
1718
1719 This is activated with the @code{\lyricmode} command, and causes
1720 input to be interpreted as lyric syllables with optional durations
1721 and associated lyric modifiers, see @ref{Vocal music}.
1722
1723 Lyric mode is also activated with the @code{\addlyrics} command.
1724 This also creates a new @code{Lyrics} context and an implicit
1725 @code{\lyricsto} command which associates the following lyrics
1726 with the preceding music.
1727
1728 @strong{Markup mode}
1729
1730 This is activated with the @code{\markup} command, and causes
1731 input to be interpreted with the syntax of markup, see
1732 @ref{Text markup commands}.
1733
1734 @c silly work-around for texinfo broken-ness
1735 @c (@strong{Note...} causes a spurious cross-reference in Info)
1736 @b{Note mode}
1737
1738 This is the default mode or it may be activated with the
1739 @code{\notemode} command.  Input is interpreted as pitches,
1740 durations, markup, etc and typeset as musical notation on a staff.
1741
1742 It is not normally necessary to specify note mode explicitly, but
1743 it may be useful to do so in certain situations, for example if you
1744 are in lyric mode, chord mode or any other mode and want to insert
1745 something that only can be done with note mode syntax.
1746
1747 For example, to indicate dynamic markings for the verses of a
1748 choral pieces it is necessary to enter note mode to interpret
1749 the markings:
1750
1751 @lilypond[verbatim,relative=2,quote]
1752 { c4 c4 c4 c4 }
1753 \addlyrics {
1754   \notemode{\set stanza = \markup{ \dynamic f 1. } }
1755   To be sung loudly
1756 }
1757 \addlyrics {
1758   \notemode{\set stanza = \markup{ \dynamic p 2. } }
1759   To be sung quietly
1760 }
1761 @end lilypond
1762
1763
1764
1765 @node Direction and placement
1766 @subsection Direction and placement
1767
1768 In typesetting music the direction and placement of many items is
1769 a matter of choice.  For example, the stems of notes can
1770 be directed up or down; lyrics, dynamics, and other expressive
1771 marks may be placed above or below the staff; text may be aligned
1772 left, right or center; etc.  Most of these choices may be left to
1773 be determined automatically by LilyPond, but in some cases it may
1774 be desirable to force a particular direction or placement.
1775
1776 @strong{Default actions}
1777
1778 By default some directions are always up or always down (e.g.
1779 dynamics or fermata), while other things can alternate between
1780 up or down based on the stem direction (like slurs or accents).
1781
1782 @c TODO Add table showing these
1783
1784 @strong{Context layout order}
1785
1786 Contexts are normally positioned in a system from top to bottom
1787 in the order in which they are encountered.  Note, however, that
1788 a context will be created implicitly if a command is encountered
1789 when there is no suitable context available to contain it.  When
1790 contexts are nested, the outer context will exclude inner contexts
1791 which are not included in its @qq{accepts} list; excluded contexts
1792 will be repositioned below the outer context.
1793
1794 The default order in which contexts are laid out and the
1795 @qq{accepts} list can be changed, see @ref{Aligning contexts}.
1796
1797 @strong{Articulation direction indicators}
1798
1799 When adding articulations to notes the direction indicator,
1800 @code{^} (meaning @qq{up}), @code{_} (meaning @qq{down}) or
1801 @code{-} (meaning @qq{use default direction}), can usually be
1802 omitted, in which case @code{-} is assumed.  But a direction
1803 indicator is @strong{always} required before
1804
1805 @itemize
1806 @item @code{\tweak} commands
1807 @item @code{\markup} commands
1808 @item @code{\tag} commands
1809 @item string markups, e.g. -"string"
1810 @item fingering instructions, e.g. @code{-1}
1811 @item articulation shortcuts, e.g. @code{-.}, @code{->}, @code{--}
1812 @end itemize
1813
1814 @strong{The direction property}
1815
1816 The position or direction of many layout objects is controlled
1817 by the @code{direction} property.
1818
1819 The value of the @code{direction} property may be
1820 set to @code{1}, meaning @qq{up} or @qq{above}, or to @code{-1},
1821 meaning @qq{down} or @qq{below}.  The symbols @code{UP} and
1822 @code{DOWN} may be used instead of @code{1} and @code{-1}
1823 respectively.  The default direction may be specified by setting
1824 @code{direction} to @code{0} or @code{CENTER}.  Alternatively,
1825 in many cases predefined commands
1826 exist to specify the direction.  These are all of the form
1827
1828 @noindent
1829 @code{\xxxUp}, @code{xxxDown}, @code{xxxNeutral}
1830
1831 @noindent
1832 where @code{xxxNeutral} means @qq{use the default direction}.
1833 See @rlearning{Within-staff objects}.
1834
1835 In a few cases, arpeggio being the only common example, the value
1836 of the @code{direction} property specifies whether the object
1837 is to be placed to the right or left of the parent object.  In
1838 this case @code{-1} or @code{LEFT} means @qq{to the left} and
1839 @code{1} or @code{RIGHT} means @qq{to the right}.  @code{0}
1840 or @code{CENTER} means @qq{use the default} direction, as before.
1841
1842 @ignore
1843 These all have side-axis set to #X
1844 AmbitusAccidental - direction has no effect
1845 Arpeggio - works
1846 StanzaNumber - not tried
1847 TrillPitchAccidental - not tried
1848 TrillPitchGroup - not tried
1849 @end ignore
1850
1851
1852
1853 @node Distances and measurements
1854 @subsection Distances and measurements
1855
1856 @cindex distances, absolute
1857 @cindex distances, scaled
1858
1859 @funindex \mm
1860 @funindex \cm
1861 @funindex \in
1862 @funindex \pt
1863
1864 Distances in LilyPond are of two types: absolute and scaled.
1865
1866 Absolute distances are used for specifying margins, indents, and
1867 other page layout details, and are by default specified in
1868 millimeters.  Distances may be specified in other units by
1869 following the quantity by @code{\mm}, @code{\cm},
1870 @code{\in}@tie{}(inches), or @code{\pt}@tie{}(points, 1/72.27
1871 of an inch).  Page layout distances can also be specified in
1872 scalable units (see the following paragraph) by appending
1873 @code{\staff-space} to the quantity.
1874 Page layout is described in detail in @ref{Page formatting}.
1875
1876 Scaled distances are always specified in units of the staff-space
1877 or, rarely, the half staff-space.  The staff-space is the distance
1878 between two adjacent staff lines.  The default value can be changed
1879 globally by setting the global staff size, or it can be overridden
1880 locally by changing the @code{staff-space} property of
1881 @code{StaffSymbol}.  Scaled distances automatically scale with any
1882 change to the either the global staff size or the
1883 @code{staff-space} property of @code{StaffSymbol}, but fonts scale
1884 automatically only with changes to the global staff size.
1885 The global staff size thus enables the overall size of a rendered
1886 score to be easily varied.  For the methods of setting the global
1887 staff size see @ref{Setting the staff size}.
1888
1889 @funindex magstep
1890
1891 If just a section of a score needs to be rendered to a different
1892 scale, for example an ossia section or a footnote, the global staff
1893 size cannot simply be changed as this would affect the entire score.
1894 In such cases the change in size is made by overriding both the
1895 @code{staff-space} property of @code{StaffSymbol} and the size of
1896 the fonts.  A Scheme function, @code{magstep}, is available to
1897 convert from a font size change to the equivalent change in
1898 @code{staff-space}.  For an explanation and an example of its use,
1899 see @rlearning{Length and thickness of objects}.
1900
1901 @seealso
1902
1903 Learning Manual:
1904 @rlearning{Length and thickness of objects}.
1905
1906 Notation Reference:
1907 @ref{Page formatting},
1908 @ref{Setting the staff size}.
1909
1910
1911 @node Staff symbol properties
1912 @subsection Staff symbol properties
1913
1914 @cindex adjusting staff symbol
1915 @cindex drawing staff symbol
1916 @cindex staff symbol, setting of
1917
1918 @c TODO Extend or remove this section.  See also NR 1.6.2 Staff symbol
1919 @c      Need to think of uses for these properties.  Eg 'line-positions
1920 @c      is used in a snippet to thicken centre line.
1921 @c      If retained, add @ref to here in 1.6.2  -td
1922
1923 The vertical position of staff lines and the number of staff lines
1924 can be defined at the same time.  As the following example shows,
1925 note positions are not influenced by the staff line positions.
1926
1927 @warning{The @code{'line-positions} property overrides the
1928 @code{'line-count} property.  The number of staff lines is
1929 implicitly defined by the number of elements in the list of values
1930 for @code{'line-positions}.}
1931
1932 @lilypond[verbatim,quote,relative=1]
1933 \new Staff \with {
1934   \override StaffSymbol #'line-positions = #'(7 3 0 -4 -6 -7)
1935 }
1936 { a4 e' f b | d1 }
1937 @end lilypond
1938
1939 The width of a staff can be modified.  The units are staff
1940 spaces.  The spacing of objects inside the staff is not affected by
1941 this setting.
1942
1943 @lilypond[verbatim,quote,relative=1]
1944 \new Staff \with {
1945   \override StaffSymbol #'width = #23
1946 }
1947 { a4 e' f b | d1 }
1948 @end lilypond
1949
1950
1951 @node Spanners
1952 @subsection Spanners
1953
1954 Many objects of musical notation extend over several notes or even
1955 several bars.  Examples are slurs, beams, tuplet brackets, volta
1956 repeat brackets, crescendi, trills, and glissandi.  Such objects
1957 are collectively called @qq{spanners}, and have special properties to control
1958 their appearance and behaviour.  Some of these properties are common
1959 to all spanners; others are restricted to a sub-set of the spanners.
1960
1961 All spanners support the @code{spanner-interface}.  A few, esentially
1962 those that draw a straight line between the two objects, support in
1963 addition the @code{line-spanner-interface}.
1964
1965 @unnumberedsubsubsec Using the @code{spanner-interface}
1966
1967 This interface provides two properties that apply to several spanners.
1968
1969 @strong{@i{The @code{minimum-length} property}}
1970
1971 The minimum length of the spanner is specified by the
1972 @code{minimum-length} property.  Increasing this usually has the
1973 necessary effect of increasing the spacing of the notes between the
1974 two end points.  However, this override has no effect on
1975 many spanners, as their length is determined by other considerations.
1976 A few examples where it is effective are shown below.
1977
1978 @ignore
1979 Works for:
1980   Tie
1981   MultiMeasureRest
1982   Hairpin
1983   Slur
1984   PhrasingSlur
1985
1986 Works as long as callback is made:
1987   Glissando
1988   Beam
1989
1990 Works not at all for:
1991   LyricSpace
1992   LyricHyphen
1993   LyricExtender
1994   TextSpanner
1995   System
1996
1997 @end ignore
1998
1999 @lilypond[verbatim,quote,relative=2]
2000 a~a
2001 a
2002 % increase the length of the tie
2003 -\tweak #'minimum-length #5
2004 ~a
2005 @end lilypond
2006
2007 @lilypond[verbatim,quote,relative=2]
2008 a1
2009 \compressFullBarRests
2010 R1*23
2011 % increase the length of the rest bar
2012 \once \override MultiMeasureRest #'minimum-length = #20
2013 R1*23
2014 a1
2015 @end lilypond
2016
2017 @lilypond[verbatim,quote,relative=2]
2018 a \< a a a \!
2019 % increase the length of the hairpin
2020 \override Hairpin #'minimum-length = #20
2021 a \< a a a \!
2022 @end lilypond
2023
2024 This override can also be used to increase the length of slurs and
2025 phrasing slurs:
2026
2027 @lilypond[verbatim,quote,relative=2]
2028 a( a)
2029 a
2030 -\tweak #'minimum-length #5
2031 ( a)
2032
2033 a\( a\)
2034 a
2035 -\tweak #'minimum-length #5
2036 \( a\)
2037 @end lilypond
2038
2039 For some layout objects, the @code{minimum-length} property becomes
2040 effective only if the @code{set-spacing-rods} procedure is called
2041 explicitly.  To do this, the @code{springs-and-rods} property should
2042 be set to @code{ly:spanner::set-spacing-rods}.   For example,
2043 the minimum length of a glissando has no effect unless the
2044 @code{springs-and-rods} property is set:
2045
2046 @lilypond[verbatim,quote,relative=1]
2047 % default
2048 e \glissando c'
2049
2050 % not effective alone
2051 \once \override Glissando #'minimum-length = #20
2052 e, \glissando c'
2053
2054 % effective only when both overrides are present
2055 \once \override Glissando #'minimum-length = #20
2056 \once \override Glissando #'springs-and-rods = #ly:spanner::set-spacing-rods
2057 e, \glissando c'
2058 @end lilypond
2059
2060 The same is true of the @code{Beam} object:
2061
2062 @lilypond[verbatim,quote,relative=1]
2063 % not effective alone
2064 \once \override Beam #'minimum-length = #20
2065 e8 e e e
2066
2067 % effective only when both overrides are present
2068 \once \override Beam #'minimum-length = #20
2069 \once \override Beam #'springs-and-rods = #ly:spanner::set-spacing-rods
2070 e8 e e e
2071 @end lilypond
2072
2073 @strong{@i{The @code{to-barline} property}}
2074
2075 The second useful property of the @code{spanner-interface} is
2076 @code{to-barline}.  By default this is true, causing hairpins and
2077 other spanners which are terminated on the first note of a measure to
2078 end instead on the immediately preceding bar line.  If set to false,
2079 the spanner will extend beyond the bar line and end on the note
2080 itself:
2081
2082 @lilypond[verbatim,quote,relative=2]
2083 a \< a a a a \! a a a \break
2084 \override Hairpin #'to-barline = ##f
2085 a \< a a a a \! a a a
2086 @end lilypond
2087
2088 This property is not effective for all spanners.  For example,
2089 seting it to @code{#t} has no effect on slurs or phrasing slurs
2090 or on other spanners for which terminating on the bar line would
2091 not be meaningful.
2092
2093 @unnumberedsubsubsec Using the @code{line-spanner-interface}
2094
2095 Objects which support the @code{line-spanner-interface} include
2096
2097 @itemize
2098 @item @code{DynamicTextSpanner}
2099 @item @code{Glissando}
2100 @item @code{TextSpanner}
2101 @item @code{TrillSpanner}
2102 @item @code{VoiceFollower}
2103 @end itemize
2104
2105 The routine responsible for drawing the stencils for these spanners is
2106 @code{ly:line-interface::print}.  This routine determines the
2107 exact location of the two end points and draws a line
2108 between them, in the style requested.  The locations of the two
2109 end points of the spanner are computed on-the-fly, but it is
2110 possible to override their Y-coordinates.  The
2111 properties which need to be specified are nested
2112 two levels down within the property hierarchy, but the syntax of
2113 the @code{\override} command is quite simple:
2114
2115 @lilypond[relative=2,quote,verbatim]
2116 e2 \glissando b
2117 \once \override Glissando #'bound-details #'left #'Y = #3
2118 \once \override Glissando #'bound-details #'right #'Y = #-2
2119 e2 \glissando b
2120 @end lilypond
2121
2122 The units for the @code{Y} property are @code{staff-space}s,
2123 with the center line of the staff being the zero point.
2124 For the glissando, this is the value for @code{Y} at the
2125 X-coordinate corresponding to the center point of each note head,
2126 if the line is imagined to be extended to there.
2127
2128 If @code{Y} is not set, the value is computed from the vertical
2129 position of the corresponding attachment point of the spanner.
2130
2131 In case of a line break, the values for the end points are
2132 specified by the @code{left-broken} and @code{right-broken}
2133 sub-lists of @code{bound-details}.  For example:
2134
2135 @lilypond[relative=2,ragged-right,verbatim,fragment]
2136 \override Glissando #'breakable = ##t
2137 \override Glissando #'bound-details #'right-broken #'Y = #-3
2138 c1 \glissando \break
2139 f1
2140 @end lilypond
2141
2142
2143 A number of further properties of the @code{left} and
2144 @code{right} sub-lists of the @code{bound-details} property
2145 may be modified in the same way as @code{Y}:
2146
2147 @table @code
2148 @item Y
2149 This sets the Y-coordinate of the end point, in @code{staff-space}s
2150 offset from the staff center line.  By default, it is the center of
2151 the bound object, so a glissando points to the vertical center of
2152 the note head.
2153
2154 For horizontal spanners, such as text spanners and trill spanners,
2155 it is hardcoded to 0.
2156
2157 @item attach-dir
2158 This determines where the line starts and ends in the X-direction,
2159 relative to the bound object.  So, a value of @code{-1} (or
2160 @code{LEFT}) makes the line start/end at the left side of the note
2161 head it is attached to.
2162
2163 @item X
2164 This is the absolute X-coordinate of the end point.  It is usually
2165 computed on the fly, and overriding it has little useful effect.
2166
2167 @item stencil
2168 Line spanners may have symbols at the beginning or end, which is
2169 contained in this sub-property.  This is for internal use; it is
2170 recommended that @code{text} be used instead.
2171
2172 @item text
2173 This is a markup that is evaluated to yield the stencil.  It is used
2174 to put @i{cresc.}, @i{tr} and other text on horizontal spanners.
2175
2176 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
2177 \override TextSpanner #'bound-details #'left #'text
2178    = \markup { \small \bold Slower }
2179 c2\startTextSpan b c a\stopTextSpan
2180 @end lilypond
2181
2182 @item stencil-align-dir-y
2183 @item stencil-offset
2184 Without setting one of these, the stencil is simply put at the
2185 end-point, centered on the line, as defined by the @code{X} and
2186 @code{Y} sub-properties.  Setting either @code{stencil-align-dir-y}
2187 or @code{stencil-offset} will move the symbol at the edge vertically
2188 relative to the end point of the line:
2189
2190 @lilypond[relative=1,fragment,verbatim]
2191 \override TextSpanner #'bound-details
2192   #'left #'stencil-align-dir-y = #-2
2193 \override TextSpanner #'bound-details
2194   #'right #'stencil-align-dir-y = #UP
2195
2196 \override TextSpanner #'bound-details
2197   #'left #'text = #"ggg"
2198 \override TextSpanner #'bound-details
2199   #'right #'text = #"hhh"
2200 c4^\startTextSpan c c c \stopTextSpan
2201 @end lilypond
2202
2203 Note that negative values move the text @emph{up}, contrary to the
2204 effect that might be expected, as a value of @code{-1} or
2205 @code{DOWN} means align the @emph{bottom} edge of the text with
2206 the spanner line.  A value of @code{1} or @code{UP} aligns
2207 the top edge of the text with the spanner line.
2208
2209 @item arrow
2210 Setting this sub-property to @code{#t} produces an arrowhead at the
2211 end of the line.
2212
2213 @item padding
2214 This sub-property controls the space between the specified
2215 end point of the line and the actual end.  Without padding, a
2216 glissando would start and end in the center of each note head.
2217
2218 @end table
2219
2220 The music function @code{\endSpanners} terminates the spanner
2221 which starts on the immediately following note prematurely.  It
2222 is terminated after exactly one note, or at the following bar line
2223 if @code{to-barline} is true and a bar line occurs before the next
2224 note.
2225
2226 @lilypond[verbatim,quote,ragged-right,relative=2,fragment]
2227 \endSpanners
2228 c2 \startTextSpan c2 c2
2229 \endSpanners
2230 c2 \< c2 c2
2231 @end lilypond
2232
2233 When using @code{\endSpanners} it is not necessary to close
2234 \startTextSpan with \stopTextSpan, nor is it necessary to close
2235 hairpins with @code{\!}.
2236
2237
2238
2239 @seealso
2240
2241 Internals Reference: @rinternals{TextSpanner},
2242 @rinternals{Glissando}, @rinternals{VoiceFollower},
2243 @rinternals{TrillSpanner},
2244 @rinternals{line-spanner-interface}.
2245
2246
2247 @node Visibility of objects
2248 @subsection Visibility of objects
2249
2250 @cindex objects, visibility of
2251 @cindex grobs, visibility of
2252 @cindex visibility of objects
2253
2254 There are four main ways in which the visibility of layout objects
2255 can be controlled: their stencil can be removed, they can be made
2256 transparent, they can be colored white, or their
2257 @code{break-visibility} property can be overridden.  The first
2258 three apply to all layout objects; the last to just a few -- the
2259 @emph{breakable} objects.  The Learning Manual introduces these
2260 four techniques, see @rlearning{Visibility and color of objects}.
2261
2262 There are also a few other techniques which are specific to
2263 certain layout objects.  These are covered under Special
2264 considerations.
2265
2266 @menu
2267 * Removing the stencil::
2268 * Making objects transparent::
2269 * Painting objects white::
2270 * Using break-visibility::
2271 * Special considerations::
2272 @end menu
2273
2274
2275 @node Removing the stencil
2276 @unnumberedsubsubsec Removing the stencil
2277
2278 @cindex stencil, removing
2279
2280 Every layout object has a stencil property.  By default this is set
2281 to the specific function which draws that object.  If this property
2282 is overridden to @code{#f} no function will be called and the object
2283 will not be drawn.  The default action can be recovered with
2284 @code{\revert}.
2285
2286 @lilypond[quote,verbatim,relative=1]
2287 a1 a
2288 \override Score.BarLine #'stencil = ##f
2289 a a
2290 \revert Score.BarLine #'stencil
2291 a a a
2292 @end lilypond
2293
2294 @node Making objects transparent
2295 @unnumberedsubsubsec Making objects transparent
2296
2297 @cindex transparent, making objects
2298
2299 Every layout object has a transparent property which by default is
2300 set to @code{#f}.  If set to @code{#t} the object still occupies
2301 space but is made invisible.
2302
2303 @lilypond[quote,verbatim,relative=2]
2304 a4 a
2305 \once \override NoteHead #'transparent = ##t
2306 a a
2307 @end lilypond
2308
2309 @node Painting objects white
2310 @unnumberedsubsubsec Painting objects white
2311
2312 @cindex objects, coloring
2313 @cindex coloring objects
2314 @cindex layers
2315 @cindex printing order
2316 @cindex overwriting objects
2317 @cindex objects, overwriting
2318 @cindex grobs, overwriting
2319
2320 Every layout object has a color property which by default is set
2321 to @code{black}.  If this is overridden to @code{white} the object
2322 will be indistinguishable from the white background.  However,
2323 if the object crosses other objects the color of the crossing
2324 points will be determined by the order in which they are drawn,
2325 and this may leave a ghostly image of the white object, as shown
2326 here:
2327
2328 @lilypond[quote,verbatim,relative=2]
2329 \override Staff.Clef #'color = #white
2330 a1
2331 @end lilypond
2332
2333 This may be avoided by changing the order of printing the objects.
2334 All layout objects have a @code{layer} property which should be set
2335 to an integer.  Objects with the lowest value of @code{layer} are
2336 drawn first, then objects with progressively higher values are drawn,
2337 so objects with higher values overwrite objects with lower values.
2338 By default most objects are assigned a @code{layer} value of
2339 @code{1}, although a few objects, including @code{StaffSymbol} and
2340 @code{BarLine}, are assigned a value of @code{0}.  The order of
2341 printing objects with the same value of @code{layer} is indeterminate.
2342
2343 In the example above the white clef, with a default @code{layer}
2344 value of @code{1}, is drawn after the staff lines (default
2345 @code{layer} value @code{0}), so overwriting them.  To change this,
2346 the @code{Clef} object must be given in a lower value of
2347 @code{layer}, say @code{-1}, so that it is drawn earlier:
2348
2349 @lilypond[quote,verbatim,relative=2]
2350 \override Staff.Clef #'color = #white
2351 \override Staff.Clef #'layer = #-1
2352 a1
2353 @end lilypond
2354
2355 @node Using break-visibility
2356 @unnumberedsubsubsec Using break-visibility
2357
2358 @c TODO Add making other objects breakable
2359
2360 @cindex break-visibility
2361
2362 Most layout objects are printed only once, but some like
2363 bar lines, clefs, time signatures and key signatures, may need
2364 to be printed twice when a line break occurs -- once at the end
2365 of the line and again at the start of the next line.  Such
2366 objects are called @emph{breakable}, and have a property, the
2367 @code{break-visibility} property to control their visibility
2368 at the three positions in which they may appear -- at the
2369 start of a line, within a line if they are changed, and at the
2370 end of a line if a change takes place there.
2371
2372 For example, the time signature
2373 by default will be printed at the start of the first line, but
2374 nowhere else unless it changes, when it will be printed at the
2375 point at which the change occurs.  If this change occurs at the
2376 end of a line the new time signature will be printed at the start
2377 of the next line and a cautionary time signature will be printed
2378 at the end of the previous line as well.
2379
2380 This behaviour is controlled by the @code{break-visibility}
2381 property, which is explained in
2382 @c Leave this ref on a newline - formats incorrectly otherwise -td
2383 @rlearning{Visibility and color of objects}.  This property takes
2384 a vector of three booleans which, in order, determine whether the
2385 object is printed at the end of, within the body of, or at the
2386 beginning of a line.  Or to be more precise, before a line break,
2387 where there is no line break, or after a line break.
2388
2389 Alternatively, these eight combinations may be specified
2390 by pre-defined functions, defined in @file{scm/output-lib.scm},
2391 where the last three columns indicate whether the layout objects
2392 will be visible in the positions shown at the head of the columns:
2393
2394 @multitable {@code{begin-of-line-invisible}} {@code{'#(#t #t #t)}} {yes} {yes} {yes}
2395 @headitem Function                   @tab Vector                  @tab Before @tab At no    @tab After
2396 @headitem form                       @tab form                    @tab break  @tab break    @tab break
2397
2398 @item @code{all-visible}             @tab @code{'#(#t #t #t)}     @tab yes    @tab yes      @tab yes
2399 @item @code{begin-of-line-visible}   @tab @code{'#(#f #f #t)}     @tab no     @tab no       @tab yes
2400 @item @code{center-visible}          @tab @code{'#(#f #t #f)}     @tab no     @tab yes      @tab no
2401 @item @code{end-of-line-visible}     @tab @code{'#(#t #f #f)}     @tab yes    @tab no       @tab no
2402 @item @code{begin-of-line-invisible} @tab @code{'#(#t #t #f)}     @tab yes    @tab yes      @tab no
2403 @item @code{center-invisible}        @tab @code{'#(#t #f #t)}     @tab yes    @tab no       @tab yes
2404 @item @code{end-of-line-invisible}   @tab @code{'#(#f #t #t)}     @tab no     @tab yes      @tab yes
2405 @item @code{all-invisible}           @tab @code{'#(#f #f #f)}     @tab no     @tab no       @tab no
2406 @end multitable
2407
2408 The default settings of @code{break-visibility} depend on the
2409 layout object.  The following table shows all the layout objects
2410 of interest which are affected by @code{break-visibility} and the
2411 default setting of this property:
2412
2413 @multitable @columnfractions .3 .3 .4
2414
2415 @headitem Layout object   @tab Usual context  @tab Default setting
2416
2417 @c omit Ambitus as it appears not to be affected by break-visibility -td
2418 @c @item @code{Ambitus}          @tab as specified   @tab @code{begin-of-line-visible}
2419 @item @code{BarLine}             @tab @code{Score}          @tab calculated
2420 @item @code{BarNumber}           @tab @code{Score}          @tab @code{begin-of-line-visible}
2421 @c omit the following item until it can be explained -td
2422 @c @item @code{BreakAlignGroup}  @tab @code{Score}          @tab calculated
2423 @item @code{BreathingSign}       @tab @code{Voice}          @tab @code{begin-of-line-invisible}
2424 @item @code{Clef}                @tab @code{Staff}          @tab @code{begin-of-line-visible}
2425 @item @code{Custos}              @tab @code{Staff}          @tab @code{end-of-line-visible}
2426 @item @code{DoublePercentRepeat} @tab @code{Voice}          @tab @code{begin-of-line-invisible}
2427 @c omit KeyCancellation until it can be explained -td
2428 @c @item @code{KeyCancellation}  @tab ??             @tab @code{begin-of-line-invisible}
2429 @item @code{KeySignature}        @tab @code{Staff}          @tab @code{begin-of-line-visible}
2430 @c omit LeftEdge until it can be explained -td
2431 @c @item @code{LeftEdge}         @tab @code{Score}          @tab @code{center-invisible}
2432 @item @code{OctavateEight}       @tab @code{Staff}          @tab @code{begin-of-line-visible}
2433 @item @code{RehearsalMark}       @tab @code{Score}          @tab @code{end-of-line-invisible}
2434 @item @code{TimeSignature}       @tab @code{Staff}          @tab @code{all-visible}
2435
2436 @end multitable
2437
2438 The example below shows the use of the vector form to control the
2439 visibility of barlines:
2440
2441 @lilypond[quote,verbatim,relative=1,ragged-right]
2442 f4 g a b
2443 f4 g a b
2444 % Remove bar line at the end of the current line
2445 \once \override Score.BarLine #'break-visibility = #'#(#f #t #t)
2446 \break
2447 f4 g a b
2448 f4 g a b
2449 @end lilypond
2450
2451 Although all three components of the vector used to override
2452 @code{break-visibility} must be present, not all of them are
2453 effective with every layout object, and some combinations may
2454 even give errors.  The following limitations apply:
2455
2456 @itemize @bullet
2457 @item Bar lines cannot be printed at start of line.
2458 @item A bar number cannot be printed at the start of the first
2459 line unless it is set to be different from 1.
2460 @item Clef -- see below
2461 @item Double percent repeats are either all printed or all
2462 suppressed.  Use begin-of line-invisible to print and
2463 all-invisible to suppress.
2464 @item Key signature -- see below
2465 @item OctavateEight -- see below
2466 @end itemize
2467
2468 @node Special considerations
2469 @unnumberedsubsubsec Special considerations
2470
2471 @strong{@emph{Visibility following explicit changes}}
2472
2473 @cindex key signature, visibility following explicit change
2474 @cindex explicitKeySignatureVisibility
2475 @cindex clef, visibility following explicit change
2476 @cindex explicitClefVisibility
2477
2478 The @code{break-visibility} property controls the visibility of
2479 key signatures and changes of clef only at the start of lines,
2480 i.e. after a break.  It has no effect on the visibility of the
2481 key signature or clef following an explicit key change or an
2482 explicit clef change within or at the end of a line.  In the
2483 following example the key signature following the explicit change
2484 to B-flat major is still visible, even though @code{all-invisible}
2485 is set.
2486
2487 @lilypond[quote,verbatim,relative=1,ragged-right]
2488 \key g \major
2489 f4 g a b
2490 % Try to remove all key signatures
2491 \override Staff.KeySignature #'break-visibility = #all-invisible
2492 \key bes \major
2493 f4 g a b
2494 \break
2495 f4 g a b
2496 f4 g a b
2497 @end lilypond
2498
2499 The visibility of such explicit key signature and clef changes is
2500 controlled by the @code{explicitKeySignatureVisibility} and
2501 @code{explicitClefVisibility} properties.  These are the equivalent
2502 of the @code{break-visibility} property and both take a vector of
2503 three booleans or the predefined functions listed above, exactly like
2504 @code{break-visibility}.  Both are properties of the Staff context,
2505 not the layout objects themselves, and so they are set using the
2506 @code{\set} command.  Both are set by default to @code{all-visible}.
2507 These properties control only the visibility of key signatures and
2508 clefs resulting from explicit changes and do not affect key
2509 signatures and clefs at the beginning of lines;
2510 @code{break-visibility} must still be overridden in the appropriate
2511 object to remove these.
2512
2513 @lilypond[quote,verbatim,relative=1,ragged-right]
2514 \key g \major
2515 f4 g a b
2516 \set Staff.explicitKeySignatureVisibility = #all-invisible
2517 \override Staff.KeySignature #'break-visibility = #all-invisible
2518 \key bes \major
2519 f4 g a b \break
2520 f4 g a b
2521 f4 g a b
2522 @end lilypond
2523
2524 @strong{@emph{Visibility of cautionary accidentals}}
2525
2526 To remove the cautionary accidentals printed at an explicit key
2527 change, set the Staff context property @code{printKeyCancellation}
2528 to @code{#f}:
2529
2530 @lilypond[quote,verbatim,relative=1,ragged-right]
2531 \key g \major
2532 f4 g a b
2533 \set Staff.explicitKeySignatureVisibility = #all-invisible
2534 \set Staff.printKeyCancellation = ##f
2535 \override Staff.KeySignature #'break-visibility = #all-invisible
2536 \key bes \major
2537 f4 g a b \break
2538 f4 g a b
2539 f4 g a b
2540 @end lilypond
2541
2542 With these overrides only the accidentals before the notes remain
2543 to indicate the change of key.
2544
2545 @c TODO Add visibility of cautionary accidentals before notes
2546
2547 @strong{@emph{Automatic bars}}
2548
2549 @cindex automaticBars
2550 @cindex bar lines, suppressing
2551
2552 As a special case, the printing of bar lines can also be turned off
2553 by setting the @code{automaticBars} property in the Score context.
2554 If set to @code{#f}, bar lines will not be printed automatically;
2555 they must be explicitly created with a @code{\bar} command.  Unlike
2556 the @code{\cadenzaOn} predefined command, measures are still counted.
2557 Bar generation will resume according to that count if this property
2558 is later set to @code{#t}.  When set to @code{#f}, line breaks can
2559 occur only at explicit @code{\bar} commands.
2560
2561 @c TODO Add example
2562
2563 @strong{@emph{Octavated clefs}}
2564
2565 @cindex octavated clefs, visibility of
2566 @cindex visibility of octavated clefs
2567 @cindex clefs, visibility of octavation
2568
2569 The small octavation symbol on octavated clefs is produced by the
2570 @code{OctavateEight} layout object.  Its visibility is controlled
2571 independently from that of the @code{Clef} object, so it is
2572 necessary to apply any required @code{break-visibility} overrides
2573 to both the @code{Clef} and the @code{OctavateEight} layout objects
2574 to fully suppress such clef symbols at the start of each line.
2575
2576 For explicit clef changes, the @code{explicitClefVisibility}
2577 property controls both the clef symbol and any octavation symbol
2578 associated with it.
2579
2580
2581 @seealso
2582 Learning Manual:
2583 @rlearning{Visibility and color of objects}
2584
2585
2586 @node Line styles
2587 @subsection Line styles
2588
2589 Some performance indications, e.g., @i{rallentando} and
2590 @i{accelerando} and @i{trills} are written as text and are
2591 extended over many measures with lines, sometimes dotted or wavy.
2592
2593 These all use the same routines as the glissando for drawing the
2594 texts and the lines, and tuning their behavior is therefore also
2595 done in the same way.  It is done with a spanner, and the routine
2596 responsible for drawing the spanners is
2597 @code{ly:line-interface::print}.  This routine determines the
2598 exact location of the two @i{span points} and draws a line
2599 between them, in the style requested.
2600
2601 Here is an example showing the different line styles available,
2602 and how to tune them.
2603
2604 @lilypond[relative=2,ragged-right,verbatim,fragment]
2605 d2 \glissando d'2
2606 \once \override Glissando #'style = #'dashed-line
2607 d,2 \glissando d'2
2608 \override Glissando #'style = #'dotted-line
2609 d,2 \glissando d'2
2610 \override Glissando #'style = #'zigzag
2611 d,2 \glissando d'2
2612 \override Glissando #'style = #'trill
2613 d,2 \glissando d'2
2614 @end lilypond
2615
2616 The locations of the end-points of the spanner are computed
2617 on-the-fly for every graphic object, but it is possible to
2618 override these:
2619
2620 @c FIXME Complete
2621 @lilypond[relative=2,ragged-right,verbatim,fragment]
2622 e2 \glissando f
2623 \once \override Glissando #'bound-details #'right #'Y = #-2
2624 e2 \glissando f
2625 @end lilypond
2626
2627 The value for @code{Y} is set to @code{-2} for the right end
2628 point.  The left side may be similarly adjusted by specifying
2629 @code{left} instead of @code{right}.
2630
2631 If @code{Y} is not set, the value is computed from the vertical
2632 position of the left and right attachment points of the spanner.
2633
2634 Other adjustments of spanners are possible, for details, see
2635 @ref{Spanners}.
2636
2637 @node Rotating objects
2638 @subsection Rotating objects
2639
2640 Both layout objects and elements of markup text can be rotated by
2641 any angle about any point, but the method of doing so differs.
2642
2643 @menu
2644 * Rotating layout objects::
2645 * Rotating markup::
2646 @end menu
2647
2648 @node Rotating layout objects
2649 @unnumberedsubsubsec Rotating layout objects
2650
2651 @cindex rotating objects
2652 @cindex objects, rotating
2653
2654 All layout objects which support the @code{grob-interface} can be
2655 rotated by setting their @code{rotation} property.  This takes a
2656 list of three items: the angle of rotation counter-clockwise,
2657 and the x and y coordinates of the point relative to the object's
2658 reference point about which the rotation is to be performed.  The
2659 angle of rotation is specified in degrees and the coordinates in
2660 staff-spaces.
2661
2662 The angle of rotation and the coordinates of the rotation point must
2663 be determined by trial and error.
2664
2665 @cindex hairpins, angled
2666 @cindex angled hairpins
2667
2668 There are only a few situations where the rotation of layout
2669 objects is useful; the following example shows one situation where
2670 they may be:
2671
2672 @lilypond[quote,verbatim,relative=1]
2673 g4\< e' d' f\!
2674 \override Hairpin #'rotation = #'(20 -1 0)
2675 g,,4\< e' d' f\!
2676 @end lilypond
2677
2678 @node Rotating markup
2679 @unnumberedsubsubsec Rotating markup
2680
2681 All markup text can be rotated to lie at any angle by prefixing it
2682 with the @code{\rotate} command.  The command takes two arguments:
2683 the angle of rotation in degrees counter-clockwise and the text to
2684 be rotated.  The extents of the text are not rotated: they take
2685 their values from the extremes of the x and y coordinates of the
2686 rotated text.  In the following example the
2687 @code{outside-staff-priority} property for text is set to @code{#f}
2688 to disable the automatic collision avoidance, which would push some
2689 of the text too high.
2690
2691 @lilypond[quote,verbatim,relative=1]
2692 \override TextScript #'outside-staff-priority = ##f
2693 g4^\markup { \rotate #30 "a G" }
2694 b^\markup { \rotate #30 "a B" }
2695 des^\markup { \rotate #30 "a D-Flat" }
2696 fis^\markup { \rotate #30 "an F-Sharp" }
2697 @end lilypond
2698
2699 @node Advanced tweaks
2700 @section Advanced tweaks
2701
2702 This section discusses various approaches to fine tuning the
2703 appearance of the printed score.
2704
2705 @menu
2706 * Aligning objects::
2707 * Vertical grouping of grobs::
2708 * Modifying stencils::
2709 * Modifying shapes::
2710 @end menu
2711
2712 @seealso
2713
2714 Learning Manual:
2715 @rlearning{Tweaking output},
2716 @rlearning{Other sources of information}.
2717
2718 Notation Reference:
2719 @ref{Explaining the Internals Reference},
2720 @ref{Modifying properties},
2721 @ref{Interfaces for programmers}.
2722
2723 Installed Files:
2724 @file{scm/@/define@/-grobs@/.scm}.
2725
2726 Snippets:
2727 @rlsr{Tweaks and overrides}.
2728
2729 Internals Reference:
2730 @rinternals{All layout objects}.
2731
2732 @node Aligning objects
2733 @subsection Aligning objects
2734
2735 Graphical objects which support the @code{self-alignment-interface} and/or
2736 the @code{side-position-interface} can be
2737 aligned to a previously placed object in a variety of ways.  For a list of these objects, see
2738 @rinternals{self-alignment-interface} and @rinternals{side-position-interface}.
2739
2740 All graphical objects have a reference point, a horizontal extent and a
2741 vertical extent.  The horizontal extent is a pair of numbers
2742 giving the displacements from the reference point of the left and
2743 right edges, displacements to the left being negative.  The
2744 vertical extent is a pair of numbers giving the displacement from
2745 the reference point to the bottom and top edges, displacements down
2746 being negative.
2747
2748 An object's position on a staff is given by the values of the
2749 @code{X-offset} and @code{Y-offset} properties.  The value of
2750 @code{X-offset} gives the displacement from the x coordinate of
2751 the reference point of the parent object, and the value of
2752 @code{Y-offset} gives the displacement from the center line of the
2753 staff.   The values of @code{X-offset} and
2754 @code{Y-offset} may be set directly or may be set to be calculated
2755 by procedures in order to achieve alignment with the parent object
2756 in several ways.
2757
2758 @warning{Many objects have special positioning considerations which
2759 cause any setting of @code{X-offset} or @code{Y-offset} to be
2760 ignored or modified, even though the object supports the
2761 @code{self-alignment-interface}.}
2762
2763 For example, an accidental can be repositioned
2764 vertically by setting @code{Y-offset} but any changes to
2765 @code{X-offset} have no effect.
2766
2767 Rehearsal marks may be aligned with
2768 breakable objects such as bar lines, clef symbols, time signature
2769 symbols and key signatures.  There are special properties to be
2770 found in the @code{break-aligned-interface} for positioning rehearsal
2771 marks on such objects.
2772
2773 @menu
2774 * Setting @code{X-offset} and @code{Y-offset} directly::
2775 * Using the @code{side-position-interface}::
2776 * Using the @code{self-alignment-interface}::
2777 * Using the @code{break-aligned-interface}::
2778 @end menu
2779
2780 @node Setting @code{X-offset} and @code{Y-offset} directly
2781 @unnumberedsubsubsec Setting @code{X-offset} and @code{Y-offset} directly
2782
2783 Numerical values may be given to the @code{X-offset} and @code{Y-offset}
2784 properties of many objects.  The following example shows three
2785 notes with the default fingering position and the positions with @code{X-offset}
2786 and @code{Y-offset} modified.
2787
2788 @lilypond[verbatim,quote,relative=2]
2789 a-3
2790 a
2791 -\tweak #'X-offset #0
2792 -\tweak #'Y-offset #0
2793 -3
2794 a
2795 -\tweak #'X-offset #-1
2796 -\tweak #'Y-offset #1
2797 -3
2798 @end lilypond
2799
2800 @c TODO write more
2801
2802 @node Using the @code{side-position-interface}
2803 @unnumberedsubsubsec Using the @code{side-position-interface}
2804
2805 An object which supports the @code{side-position-interface} can be
2806 placed next to its parent object so that
2807 the specified edges of the two objects touch.  The object may be
2808 placed above, below, to the right or to the left of the parent.
2809 The parent cannot be specified; it is determined by the order of
2810 elements in the input stream.  Most objects have the associated
2811 note head as their parent.
2812
2813 The values of the @code{side-axis} and @code{direction} properties
2814 determine where the object is to be placed, as follows:
2815
2816 @c TODO add an example of each to the table
2817
2818 @multitable @columnfractions .3 .3 .3
2819 @headitem @code{side-axis}  @tab @code{direction}  @tab
2820 @headitem property          @tab property          @tab Placement
2821
2822 @item     @code{0}          @tab @code{-1}         @tab left
2823 @item     @code{0}          @tab @code{1}          @tab right
2824 @item     @code{1}          @tab @code{-1}         @tab below
2825 @item     @code{1}          @tab @code{1}          @tab above
2826
2827 @end multitable
2828
2829 When @code{side-axis} is @code{0}, @code{X-offset} should be set to
2830 the procedure @code{ly:side-position-interface::x-aligned-side}.
2831 This procedure will return the correct value of @code{X-offset} to
2832 place the object to the left or right side of the parent according
2833 to value of @code{direction}.
2834
2835 When @code{side-axis} is @code{1}, @code{Y-offset} should be set to
2836 the procedure @code{ly:side-position-interface::y-aligned-side}.
2837 This procedure will return the correct value of @code{Y-offset} to
2838 place the object to the top or bottom of the parent according
2839 to value of @code{direction}.
2840
2841 @c TODO Add examples
2842
2843 @node Using the @code{self-alignment-interface}
2844 @unnumberedsubsubsec Using the @code{self-alignment-interface}
2845
2846 @emph{Self-aligning objects horizontally}
2847
2848 The horizontal alignment of an object which supports the
2849 @code{self-alignment-interface} is controlled by the value of
2850 the @code{self-alignment-X} property, provided the object's
2851 @code{X-offset} property is set to
2852 @code{ly:self-alignment-interface::x-aligned-on-self}.
2853 @code{self-alignment-X}  may be given any
2854 real value, in units of half the total X extent of the
2855 object.  Negative values move the object to the right, positive
2856 to the left.  A value of @code{0} centers the object on the
2857 reference point of its parent, a value of @code{-1} aligns the
2858 left edge of the object on the reference point of its parent,
2859 and a value of @code{1} aligns the right edge of the object on the
2860 reference point of its parent.  The symbols @code{LEFT},
2861 @code{CENTER} and @code{RIGHT} may be used instead of the values
2862 @code{-1, 0, 1} respectively.
2863
2864 Normally the @code{\override} command would be used to modify the
2865 value of @code{self-alignment-X}, but the @code{\tweak} command
2866 can be used to separately align several annotations on a single
2867 note:
2868
2869 @lilypond[quote,verbatim,relative=1]
2870 a'
2871 -\tweak #'self-alignment-X #-1
2872 ^"left-aligned"
2873 -\tweak #'self-alignment-X #0
2874 ^"center-aligned"
2875 -\tweak #'self-alignment-X #RIGHT
2876 ^"right-aligned"
2877 -\tweak #'self-alignment-X #-2.5
2878 ^"aligned further to the right"
2879 @end lilypond
2880
2881 @emph{Self-aligning objects vertically}
2882
2883 Objects may be aligned vertically in an analogous way to aligning
2884 them horizontally if the @code{Y-offset} property is set to
2885 @code{ly:self-alignment-interface::y-aligned-on-self}.  However,
2886 other mechanisms are often involved in vertical alignment: the
2887 value of @code{Y-offset} is just one variable taken into account.
2888 This may make adjusting the value of some objects tricky.
2889 The units are just half the vertical extent of the object, which
2890 is usually quite small, so quite large numbers may be required.
2891 A value of @code{-1} aligns the lower edge of the object with
2892 the reference point of the parent object, a value of @code{0}
2893 aligns the center of the object with the reference point of the
2894 parent, and a value of @code{1} aligns the top edge of the object
2895 with the reference point of the parent.  The symbols @code{DOWN},
2896 @code{CENTER}, @code{UP} may be substituted for @code{-1, 0, 1}
2897 respectively.
2898
2899 @emph{Self-aligning objects in both directions}
2900
2901 By setting both @code{X-offset} and @code{Y-offset}, an object may
2902 be aligned in both directions simultaneously.
2903
2904 The following example shows how to adjust a fingering mark so
2905 that it nestles close to the note head.
2906
2907 @lilypond[quote,verbatim,relative=2]
2908 a
2909 -\tweak #'self-alignment-X #0.5  % move horizontally left
2910 -\tweak #'Y-offset #ly:self-alignment-interface::y-aligned-on-self
2911 -\tweak #'self-alignment-Y #-1  % move vertically up
2912 -3  % third finger
2913 @end lilypond
2914
2915 @ignore
2916 @unnumberedsubsubsec Using the @code{aligned-on-parent} procedures
2917
2918 @c Cannot document as they do not seem to operate consistently on all objects -td
2919 @c TODO investigate further
2920
2921 The @code{aligned-on-parent} procedures are used in the same way
2922 as the @code{aligned-on-self} procedures, they difference being
2923 that they permit an object to be aligned with the @emph{edges} of
2924 the parent rather than the parent's reference point.  The following
2925 example shows the difference:
2926
2927 @c TODO Add example
2928
2929 @lilypond[verbatim,quote]
2930 @end lilypond
2931
2932 @end ignore
2933
2934 @ignore
2935 @unnumberedsubsubsec Using the @code{centered-on-parent} procedures
2936
2937 @c Cannot document as they do not seem to operate consistently on all objects -td
2938 @c TODO investigate further
2939
2940 @end ignore
2941
2942 @c TODO The align-interface, BassFigureAlignment and VerticalAlignment
2943
2944 @node Using the @code{break-aligned-interface}
2945 @unnumberedsubsubsec Using the @code{break-aligned-interface}
2946
2947 Rehearsal marks may be aligned with notation objects other
2948 than bar lines.  These objects include @code{ambitus},
2949 @code{breathing-sign}, @code{clef}, @code{custos}, @code{staff-bar},
2950 @code{left-edge}, @code{key-cancellation}, @code{key-signature}, and
2951 @code{time-signature}.
2952
2953 By default, rehearsal marks will be horizontally centered above the
2954 object:
2955
2956 @lilypond[verbatim,quote,relative=1]
2957 e1
2958 % the RehearsalMark will be centered above the Clef
2959 \override Score.RehearsalMark #'break-align-symbols = #'(clef)
2960 \key a \major
2961 \clef treble
2962 \mark "↓"
2963 e
2964 % the RehearsalMark will be centered above the TimeSignature
2965 \override Score.RehearsalMark #'break-align-symbols = #'(time-signature)
2966 \key a \major
2967 \clef treble
2968 \time 3/4
2969 \mark "↓"
2970 e2.
2971 @end lilypond
2972
2973 The alignment of the rehearsal mark relative to the notation object
2974 can be changed, as shown in the following example.  In a score with
2975 multiple staves, this setting should be done for all the staves.
2976
2977 @lilypond[verbatim,quote,relative=1]
2978 % The RehearsalMark will be centered above the KeySignature
2979 \override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
2980 \key a \major
2981 \clef treble
2982 \time 4/4
2983 \mark "↓"
2984 e1
2985 % The RehearsalMark will be aligned with the left edge of the KeySignature
2986 \once \override Score.KeySignature #'break-align-anchor-alignment = #LEFT
2987 \mark "↓"
2988 \key a \major
2989 e
2990 % The RehearsalMark will be aligned with the right edge of the KeySignature
2991 \once \override Score.KeySignature #'break-align-anchor-alignment = #RIGHT
2992 \key a \major
2993 \mark "↓"
2994 e
2995 @end lilypond
2996
2997 The rehearsal mark can also be offset to the right or left of the left edge
2998 by an arbitrary amount.  The units are staff-spaces:
2999
3000 @lilypond[verbatim,quote,relative=1]
3001 % The RehearsalMark will be aligned with the left edge of the KeySignature
3002 % and then shifted right by 3.5 staff-spaces
3003 \override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
3004 \once \override Score.KeySignature #'break-align-anchor = #3.5
3005 \key a \major
3006 \mark "↓"
3007 e
3008 % The RehearsalMark will be aligned with the left edge of the KeySignature
3009 % and then shifted left by 2 staff-spaces
3010 \once \override Score.KeySignature #'break-align-anchor = #-2
3011 \key a \major
3012 \mark "↓"
3013 e
3014 @end lilypond
3015
3016
3017
3018 @node Vertical grouping of grobs
3019 @subsection Vertical grouping of grobs
3020
3021 @c FIXME Expand this section
3022
3023 The VerticalAlignment and VerticalAxisGroup grobs work together.
3024 VerticalAxisGroup groups together different grobs like Staff, Lyrics,
3025 etc.  VerticalAlignment then vertically aligns the different grobs
3026 grouped together by VerticalAxisGroup.  There is usually only one
3027 VerticalAlignment per score but every Staff, Lyrics, etc. has its own
3028 VerticalAxisGroup.
3029
3030
3031 @node Modifying stencils
3032 @subsection Modifying stencils
3033
3034 All layout objects have a @code{stencil} property which is part of
3035 the @code{grob-interface}.  By default, this property is usually
3036 set to a function specific to the object that is tailor-made to
3037 render the symbol which represents it in the output.  For example,
3038 the standard setting for the @code{stencil} property of the
3039 @code{MultiMeasureRest} object is @code{ly:multi-measure-rest::print}.
3040
3041 The standard symbol for any object can be replaced by modifying the
3042 @code{stencil} property to reference a different, specially-written,
3043 procedure.  This requires a high level of knowledge of the internal
3044 workings of LilyPond, but there is an easier way which can often
3045 produce adequate results.
3046
3047 This is to set the @code{stencil} property to the procedure which
3048 prints text -- @code{ly:text-interface::print} -- and to add a
3049 @code{text} property to the object which is set to contain the
3050 markup text which produces the required symbol.  Due to the
3051 flexibility of markup, much can be achieved -- see in particular
3052 @ref{Graphic notation inside markup}.
3053
3054 The following example demonstrates this by changing the note head
3055 symbol to a cross within a circle.
3056
3057 @lilypond[verbatim,quote]
3058 XinO = {
3059   \once \override NoteHead  #'stencil = #ly:text-interface::print
3060   \once \override NoteHead #'text = \markup {
3061     \combine
3062       \halign #-0.7 \draw-circle #0.85 #0.2 ##f
3063       \musicglyph #"noteheads.s2cross"
3064   }
3065 }
3066 \relative c'' {
3067   a a \XinO a a
3068 }
3069 @end lilypond
3070
3071 Any of the glyphs in the feta Font can be supplied to the
3072 @code{\musicglyph} markup command -- see @ref{The Feta font}.
3073
3074 @c TODO Add inserting eps files or ref to later
3075
3076 @c TODO Add inserting Postscript or ref to later
3077
3078 @seealso
3079
3080 Notation Reference:
3081 @ref{Graphic notation inside markup},
3082 @ref{Formatting text},
3083 @ref{Text markup commands},
3084 @ref{The Feta font}.
3085
3086
3087 @node Modifying shapes
3088 @subsection Modifying shapes
3089
3090 @menu
3091 * Modifying ties and slurs::
3092 @end menu
3093
3094 @node Modifying ties and slurs
3095 @unnumberedsubsubsec Modifying ties and slurs
3096
3097 Ties, slurs and phrasing slurs are drawn as third-order Bézier
3098 curves.  If the shape of the tie or slur which is calculated
3099 automatically is not optimum, the shape may be modified manually by
3100 explicitly specifying the four control points required to define
3101 a third-order Bézier curve.
3102
3103 Third-order or cubic Bézier curves are defined by four control
3104 points.  The first and fourth control points are precisely the
3105 starting and ending points of the curve.  The intermediate two
3106 control points define the shape.  Animations showing how the curve
3107 is drawn can be found on the web, but the following description
3108 may be helpful.  The curve starts from the first control point
3109 heading directly towards the second, gradually bending over to
3110 head towards the third and continuing to bend over to head towards
3111 the fourth, arriving there travelling directly from the third
3112 control point.  The curve is entirely contained in the
3113 quadrilateral defined by the four control points.
3114
3115 Here is an example of a case where the tie is not optimum, and
3116 where @code{\tieDown} would not help.
3117
3118 @lilypond[verbatim,quote,relative=1]
3119 <<
3120   { e1 ~ e }
3121 \\
3122   { r4 <g c,> <g c,> <g c,> }
3123 >>
3124 @end lilypond
3125
3126 One way of improving this tie is to manually modify its control
3127 points, as follows.
3128
3129 The coordinates of the Bézier control points are specified in units
3130 of staff-spaces.  The X@tie{}coordinate is relative to the reference
3131 point of the note to which the tie or slur is attached, and the
3132 Y@tie{}coordinate is relative to the staff center line.  The
3133 coordinates are entered as a list of four pairs of decimal numbers
3134 (reals).  One approach is to estimate the coordinates of the two
3135 end points, and then guess the two intermediate points.  The optimum
3136 values are then found by trial and error.
3137
3138 It is useful to remember that a symmetric curve requires symmetric
3139 control points, and that Bézier curves have the useful property that
3140 transformations of the curve such as translation, rotation and
3141 scaling can be achieved by applying the same transformation to the
3142 curve's control points.
3143
3144 For the example above the following override gives a satisfactory
3145 tie:
3146
3147 @lilypond[verbatim,quote,relative=1]
3148 <<
3149   \once \override Tie
3150     #'control-points = #'((1 . -1) (3 . 0.6) (12.5 . 0.6) (14.5 . -1))
3151   { e1 ~ e1 }
3152 \\
3153   { r4 <g c,> <g c,> <g c,>4  }
3154 >>
3155 @end lilypond
3156
3157 @knownissues
3158
3159 It is not possible to modify shapes of ties or slurs by changing
3160 the @code{control-points} property if there are more than one at
3161 the same musical moment, not even by using the @code{\tweak}
3162 command.
3163
3164
3165
3166