]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/user/changing-defaults.itely
Adapt doc to reflect fix for #647.
[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.51"
11
12 @node Changing defaults
13 @chapter Changing defaults
14
15
16 The purpose of LilyPond's design is to provide the finest output
17 quality as a default.  Nevertheless, it may happen that you need to
18 change this default layout.  The layout is controlled through a large
19 number of proverbial @q{knobs and switches.}  This chapter does not
20 list each and every knob.  Rather, it outlines what groups of controls
21 are available and explains how to lookup which knob to use for a
22 particular effect.
23
24
25 @cindex Internals Reference
26
27 The controls available for tuning are described in a separate
28 document, the
29 @iftex
30 Internals Reference manual.
31 @end iftex
32 @ifnottex
33 @ref{Top,Internals Reference,,lilypond-internals}.
34 @end ifnottex
35 That manual
36 lists all different variables, functions and options available in
37 LilyPond.  It is written as a HTML document, which is available
38 @c leave the @uref as one long line.
39 @uref{http://@/lilypond@/.org/@/doc/@/stable/@/Documentation/@/user/@/lilypond@/-internals/,on@/-line},
40 but is also included with the LilyPond documentation package.
41
42 There are four areas where the default settings may be changed:
43
44 @itemize
45 @item
46 Automatic notation: changing the automatic creation of notation
47 elements.  For example, changing the beaming rules.
48
49 @item
50 Output: changing the appearance of individual
51 objects.  For example, changing stem directions or the location of
52 subscripts.
53
54 @item
55 Context: changing aspects of the translation from music events to
56 notation.  For example, giving each staff a separate time signature.
57
58 @item
59 Page layout: changing the appearance of the spacing, line
60 breaks, and page dimensions.  These modifications are discussed
61 @c in @ref{notation}, and @ref{Spacing issues}.
62 @end itemize
63
64 Internally, LilyPond uses Scheme (a LISP dialect) to provide
65 infrastructure.  Overriding layout decisions in effect accesses the
66 program internals, which requires Scheme input.  Scheme elements are
67 introduced in a @code{.ly} file with the hash mark
68 @code{#}.@footnote{@rlearning{Scheme tutorial}, contains a short tutorial
69 on entering numbers, lists, strings, and symbols in Scheme.}
70
71
72 @menu
73 * Interpretation contexts::
74 * Explaining the Internals Reference::
75 * Modifying properties::
76 * Useful concepts and properties::
77 * Common properties::
78 * Advanced tweaks::
79 * Discussion of specific tweaks::
80 @end menu
81
82
83 @node Interpretation contexts
84 @section Interpretation contexts
85
86 This section describes what contexts are, and how to modify them.
87
88 @menu
89 * Contexts explained::
90 * Creating contexts::
91 * Modifying context plug-ins::
92 * Changing context default settings::
93 * Defining new contexts::
94 * Aligning contexts::
95 @end menu
96
97
98 @node Contexts explained
99 @subsection Contexts explained
100
101 @c FIXME Rethink and rewrite
102
103 >> > > - list of contexts: my *danger unmaintainable*
104 >> > > alarm just went off.  I'm 
105
106 I knew it would... And leaving out some of them is perfectly fine
107 with me.
108 I do think that a list like this, with the main contexts and a
109 brief
110 description of  what they do (perhaps also with a note about what
111 default
112 behavior is associated with each of them, but this may be
113 unmanageable),
114 should be there, and then we could simply list the remaining ones
115 without
116 further explanation and with links to the IR.
117
118
119 The Master Of All Contexts
120 ==========================
121
122     * Score
123         This is the top level notation context. No other context
124 can
125         contain a Score context. This context handles the
126         administration of time signatures. It also makes sure that
127         items such as clefs, time signatures, and key-signatures
128 are
129         aligned across staves.
130         You cannot explicitly instantiate a Score context (since
131 it is
132         not contained in any other context). It is instantiated
133         automatically when an output definition (a \score or
134 \layout
135         block) is processed. 
136         (it should also be made clear somewhere what the
137 difference is between
138         \score and \Score).
139
140 Top-level contexts: Staff containers
141 ====================================
142     * StaffGroup
143         Groups staves while adding a bracket on the left side,
144         grouping the staves together. The bar lines of the
145 contained
146         staves are connected vertically. StaffGroup only consists
147 of a
148         collection of staves, with a bracket in front and spanning
149 bar
150         lines.
151     * ChoirStaff
152         Identical to StaffGroup except that the contained staves
153 are
154         not connected vertically.
155     * GrandStaff
156         A group of staves, with a brace on the left side, grouping
157 the
158         staves together. The bar lines of the contained staves are
159         connected vertically.
160     * PianoStaff
161         Just like GrandStaff but with a forced distance between
162 the
163         staves, so cross staff beaming and slurring can be used.
164     * DrumStaff
165         Handles typesetting for percussion. Can contain DrumVoice
166     * InnerStaffGroup
167     * InnerChoirStaff
168
169 Staff-level contexts
170 ====================
171     * Staff
172         Handles clefs, bar lines, keys, accidentals. It can
173 contain
174         Voice contexts.
175     * RhythmicStaff
176         Like Staff but for printing rhythms. Pitches are
177         ignored; the notes are printed on one line.
178     * TabStaff
179         Context for generating tablature. By default lays the
180 music
181         expression out as a guitar tablature, printed on six
182 lines.
183     * VaticanaStaff
184         Same as Staff, except that it is accommodated for
185         typesetting a piece in gregorian style. 
186     * MensuralStaff
187         Same as Staff, except that it is accommodated for
188         typesetting a piece in mensural style. 
189
190 Voice-level (bottom) contexts
191 =============================
192 What is generated by default here?  The voice-level contexts
193 initiate
194 certain properties and start engravers. 
195
196     * Voice 
197         Corresponds to a voice on a staff. This context handles
198 the
199         conversion of dynamic signs, stems, beams, super- and
200         subscripts, slurs, ties, and rests.
201         You have to instantiate this explicitly if you want to
202 have
203         multiple voices on the same staff. 
204         Bottom context.
205     * VaticanaVoice
206         Same as Voice, except that it is accommodated for
207         typesetting a piece in gregorian style.  
208     * MensuralVoice
209         Same as Voice, except that it is accommodated for
210         typesetting a piece in mensural style. 
211     * Lyrics
212         Corresponds to a voice with lyrics. Handles the printing
213 of a
214         single line of lyrics.
215         Bottom context.
216     * DrumVoice
217         A voice on a percussion staff.
218     * FiguredBass
219          
220     * ChordNames
221         Typesets chord names.  This context is a `bottom' context;
222 it
223         cannot contain other contexts.
224
225 ------------------------------
226 Then the following, which I don't know what to do with:
227
228     * TabVoice
229     * GregorianTranscriptionVoice
230     * GregorianTranscriptionStaff
231
232     * FretBoards
233         Engraves fretboards from chords. Not easy... Not
234 documented.
235     * NoteNames
236
237     * CueVoice Not documented
238     * Global
239         Hard coded entry point for LilyPond. Cannot be tuned.
240     * Devnull
241         Silently discards all musical information given to this
242 context.
243
244
245
246 @node Creating contexts
247 @subsection Creating contexts
248
249 @c TODO \new Score and \score
250 @c TODO more complete descriptions rather than learning style
251
252 For scores with only one voice and one staff, contexts are
253 created automatically.  For more complex scores, it is necessary to
254 create them by hand.  There are three commands that do this.
255
256 @itemize
257
258 @item
259 The easiest command is @code{\new}, and it also the quickest to type.
260 It is prepended to a music expression, for example
261
262 @funindex \new
263 @cindex new contexts
264 @cindex Context, creating
265
266 @example
267 \new @var{type} @var{music expression}
268 @end example
269
270 @noindent
271 where @var{type} is a context name (like @code{Staff} or
272 @code{Voice}).  This command creates a new context, and starts
273 interpreting the @var{music expression} with that.
274
275 A practical application of @code{\new} is a score with many
276 staves.  Each part that should be on its own staff, is preceded with
277 @code{\new Staff}.
278
279 @lilypond[quote,verbatim,relative=2,ragged-right,fragment]
280 <<
281   \new Staff { c4 c }
282   \new Staff { d4 d }
283 >>
284 @end lilypond
285
286 The @code{\new} command may also give a name to the context,
287
288 @example
289 \new @var{type} = @var{id} @var{music}
290 @end example
291 However, this user specified name is only used if there is no other
292 context already earlier with the same name.
293
294
295 @funindex \context
296
297 @item
298 Like @code{\new}, the @code{\context} command also directs a music
299 expression to a context object, but gives the context an explicit name.  The
300 syntax is
301
302 @example
303 \context @var{type} = @var{id} @var{music}
304 @end example
305
306 This form will search for an existing context of type @var{type}
307 called @var{id}.  If that context does not exist yet, a new
308 context with the specified name is created.  This is useful if
309 the context is referred to later on.  For example, when
310 setting lyrics the melody is in a named context
311
312 @example
313 \context Voice = "@b{tenor}" @var{music}
314 @end example
315
316 @noindent
317 so the texts can be properly aligned to its notes,
318
319 @example
320 \new Lyrics \lyricsto "@b{tenor}" @var{lyrics}
321 @end example
322
323 @noindent
324
325 Another possible use of named contexts is funneling two different
326 music expressions into one context.  In the following example,
327 articulations and notes are entered separately,
328
329 @example
330 music = @{ c4 c4 @}
331 arts = @{ s4-. s4-> @}
332 @end example
333
334 They are combined by sending both to the same @code{Voice} context,
335
336 @example
337 <<
338   \new Staff \context Voice = "A" \music
339   \context Voice = "A" \arts
340 >>
341 @end example
342 @lilypond[quote,ragged-right]
343 music = { c4 c4 }
344 arts = { s4-. s4-> }
345 \relative c'' <<
346   \new Staff \context Voice = "A" \music
347   \context Voice = "A" \arts
348 >>
349 @end lilypond
350
351 With this mechanism, it is possible to define an Urtext (original
352 edition), with the option to put several distinct articulations on the
353 same notes.
354
355 @cindex creating contexts
356
357 @item
358 The third command for creating contexts is
359 @example
360 \context @var{type} @var{music}
361 @end example
362
363
364 @noindent
365 This is similar to @code{\context} with @code{= @var{id}}, but matches
366 any context of type @var{type}, regardless of its given name.
367
368 This variant is used with music expressions that can be interpreted at
369 several levels.  For example, the @code{\applyOutput} command (see
370 @ref{Running a function on all layout objects}).  Without an explicit
371 @code{\context}, it is usually applied to @code{Voice}
372
373 @example
374 \applyOutput #'@var{context} #@var{function}   % apply to Voice
375 @end example
376
377 To have it interpreted at the @code{Score} or @code{Staff} level use
378 these forms
379
380 @example
381 \applyOutput #'Score #@var{function}
382 \applyOutput #'Staff #@var{function}
383 @end example
384
385 @end itemize
386
387
388 @node Modifying context plug-ins
389 @subsection Modifying context plug-ins
390
391 @c TODO Should this be Modifying engravers or Modifying contexts?
392
393 Notation contexts (like @code{Score} and @code{Staff}) not only
394 store properties,
395 they also contain plug-ins called @q{engravers} that create notation
396 elements.  For example, the @code{Voice} context contains a
397 @code{Note_head_engraver} and the @code{Staff} context contains a
398 @code{Key_signature_engraver}.
399
400 For a full a description of each plug-in, see
401 @ifhtml
402 @rinternals{Engravers and Performers}.
403 @end ifhtml
404 @ifnothtml
405 Internals Reference @expansion{} Translation @expansion{} Engravers.
406 @end ifnothtml
407 Every context described in
408 @ifhtml
409 @rinternals{Contexts}
410 @end ifhtml
411 @ifnothtml
412 Internals Reference @expansion{} Translation @expansion{} Context.
413 @end ifnothtml
414 lists the engravers used for that context.
415
416
417 It can be useful to shuffle around these plug-ins.  This is done by
418 starting a new context with @code{\new} or @code{\context}, and
419 modifying it,
420
421 @funindex \with
422
423 @example
424 \new @var{context} \with @{
425   \consists @dots{}
426   \consists @dots{}
427   \remove @dots{}
428   \remove @dots{}
429   @emph{etc.}
430 @}
431 @{
432   @emph{..music..}
433 @}
434 @end example
435
436 @noindent
437 where the @dots{} should be the name of an engraver.  Here is a simple
438 example which removes @code{Time_signature_engraver} and
439 @code{Clef_engraver} from a @code{Staff} context,
440
441 @lilypond[quote,relative=1,verbatim,fragment]
442 <<
443   \new Staff {
444     f2 g
445   }
446   \new Staff \with {
447      \remove "Time_signature_engraver"
448      \remove "Clef_engraver"
449   } {
450     f2 g2
451   }
452 >>
453 @end lilypond
454
455 In the second staff there are no time signature or clef symbols.  This
456 is a rather crude method of making objects disappear since it will affect
457 the entire staff.  This method also influences the spacing, which may or
458 may not be desirable.  More sophisticated methods of blanking objects
459 are shown in @rlearning{Visibility and color of objects}.
460
461 The next example shows a practical application.  Bar lines and time
462 signatures are normally synchronized across the score.  This is done
463 by the @code{Timing_translator} and @code{Default_bar_line_engraver}.
464 This plug-in keeps an administration of time signature, location
465 within the measure, etc.  By moving these engraver from @code{Score} to
466 @code{Staff} context, we can have a score where each staff has its own
467 time signature.
468
469 @cindex polymetric scores
470 @cindex Time signatures, multiple
471
472 @lilypond[quote,relative=1,ragged-right,verbatim,fragment]
473 \new Score \with {
474   \remove "Timing_translator"
475   \remove "Default_bar_line_engraver"
476 } <<
477   \new Staff \with {
478     \consists "Timing_translator"
479     \consists "Default_bar_line_engraver"
480   } {
481       \time 3/4
482       c4 c c c c c
483   }
484   \new Staff \with {
485     \consists "Timing_translator"
486     \consists "Default_bar_line_engraver"
487   } {
488        \time 2/4
489        c4 c c c c c
490   }
491 >>
492 @end lilypond
493
494
495 @node Changing context default settings
496 @subsection Changing context default settings
497
498 The adjustments of the previous subsections (
499 @ref{The \set command}, @ref{Modifying context plug-ins}, and
500 @ref{Overview of modifying properties}) can also be entered
501 separately from the music in the @code{\layout} block,
502
503 @example
504 \layout @{
505   @dots{}
506   \context @{
507     \Staff
508
509     \set fontSize = #-2
510     \override Stem #'thickness = #4.0
511     \remove "Time_signature_engraver"
512   @}
513 @}
514 @end example
515
516 The @code{\Staff} command brings in the existing definition of the
517 staff context so that it can be modified.
518
519 The statements
520 @example
521 \set fontSize = #-2
522 \override Stem #'thickness = #4.0
523 \remove "Time_signature_engraver"
524 @end example
525
526 @noindent
527 affect all staves in the score.  Other contexts can be modified
528 analogously.
529
530 The @code{\set} keyword is optional within the @code{\layout} block, so
531
532 @example
533 \context @{
534   @dots{}
535   fontSize = #-2
536 @}
537 @end example
538
539 @noindent
540 will also work.
541
542
543
544 @knownissues
545
546 It is not possible to collect context changes in a variable and apply
547 them to a @code{\context} definition by referring to that variable.
548
549 The @code{\RemoveEmptyStaffContext} will overwrite your current
550 @code{\Staff} settings.  If you wish to change the defaults for a
551 staff which uses @code{\RemoveEmptyStaffContext}, you must do so
552 after calling @code{\RemoveEmptyStaffContext}, ie
553
554 @example
555 \layout @{
556   \context @{
557     \RemoveEmptyStaffContext
558
559     \override Stem #'thickness = #4.0
560   @}
561 @}
562 @end example
563
564 TODO: add \with in here.
565
566
567
568 @node Defining new contexts
569 @subsection Defining new contexts
570
571 Specific contexts, like @code{Staff} and @code{Voice}, are made of
572 simple building blocks.  It is possible to create new types of
573 contexts with different combinations of engraver plug-ins.
574
575 The next example shows how to build a different type of
576 @code{Voice} context from scratch.  It will be similar to
577 @code{Voice}, but only prints centered slash note heads.  It can be used
578 to indicate improvisation in jazz pieces,
579
580 @lilypond[quote,ragged-right]
581 \layout { \context {
582   \name ImproVoice
583   \type "Engraver_group"
584   \consists "Note_heads_engraver"
585   \consists "Text_engraver"
586   \consists Pitch_squash_engraver
587   squashedPosition = #0
588   \override NoteHead #'style = #'slash
589   \override Stem #'transparent = ##t
590   \alias Voice
591 }
592 \context { \Staff
593   \accepts "ImproVoice"
594 }}
595
596 \relative c'' {
597   a4 d8 bes8 \new ImproVoice { c4^"ad lib" c
598    c4 c^"undress" c_"while playing :)" c }
599   a1
600 }
601 @end lilypond
602
603
604 These settings are defined within a @code{\context} block inside a
605 @code{\layout} block,
606
607 @example
608 \layout @{
609   \context @{
610     @dots{}
611   @}
612 @}
613 @end example
614
615 In the following discussion, the example input shown should go in place
616 of the @dots{} in the previous fragment.
617
618 First it is necessary to define a name for the new context:
619
620 @example
621 \name ImproVoice
622 @end example
623
624 Since it is similar to the @code{Voice}, we want commands that work
625 on (existing) @code{Voice}s to remain working.  This is achieved by
626 giving the new context an alias @code{Voice},
627
628 @example
629 \alias Voice
630 @end example
631
632 The context will print notes and instructive texts, so we need to add
633 the engravers which provide this functionality,
634
635 @example
636 \consists Note_heads_engraver
637 \consists Text_engraver
638 @end example
639
640 but we only need this on the center line,
641
642 @example
643 \consists Pitch_squash_engraver
644 squashedPosition = #0
645 @end example
646
647 The @rinternals{Pitch_squash_engraver} modifies note heads (created
648 by @rinternals{Note_heads_engraver}) and sets their vertical
649 position to the value of @code{squashedPosition}, in this case@tie{}@code{0},
650 the center line.
651
652 The notes look like a slash, and have no stem,
653
654 @example
655 \override NoteHead #'style = #'slash
656 \override Stem #'transparent = ##t
657 @end example
658
659 All these plug-ins have to cooperate, and this is achieved with a
660 special plug-in, which must be marked with the keyword @code{\type}.
661 This should always be @rinternals{Engraver_group},
662
663 @example
664 \type "Engraver_group"
665 @end example
666
667 Put together, we get
668
669 @example
670 \context @{
671   \name ImproVoice
672   \type "Engraver_group"
673   \consists "Note_heads_engraver"
674   \consists "Text_engraver"
675   \consists Pitch_squash_engraver
676   squashedPosition = #0
677   \override NoteHead #'style = #'slash
678   \override Stem #'transparent = ##t
679   \alias Voice
680 @}
681 @end example
682
683 @funindex \accepts
684 Contexts form hierarchies.  We want to hang the @code{ImproVoice}
685 under @code{Staff}, just like normal @code{Voice}s.  Therefore, we
686 modify the @code{Staff} definition with the @code{\accepts}
687 command,
688
689 @example
690 \context @{
691   \Staff
692   \accepts ImproVoice
693 @}
694 @end example
695
696 @funindex \denies
697 The opposite of @code{\accepts} is @code{\denies},
698 which is sometimes needed when reusing existing context definitions.
699
700 Putting both into a @code{\layout} block, like
701
702 @example
703 \layout @{
704   \context @{
705     \name ImproVoice
706     @dots{}
707   @}
708   \context @{
709     \Staff
710     \accepts "ImproVoice"
711   @}
712 @}
713 @end example
714
715 Then the output at the start of this subsection can be entered as
716
717 @example
718 \relative c'' @{
719   a4 d8 bes8
720   \new ImproVoice @{
721     c4^"ad lib" c
722     c4 c^"undress"
723     c c_"while playing :)"
724   @}
725   a1
726 @}
727 @end example
728
729
730 @node Aligning contexts
731 @subsection Aligning contexts
732
733 New contexts may be aligned above or below existing contexts.  This
734 could be useful in setting up a vocal staff (@rlearning{Vocal ensembles}) and
735 in ossia,
736
737 @c TODO Better example needed.  Ref LM, and expand on it.
738
739 @cindex ossia
740 @findex alignAboveContext
741 @findex alignBelowContext
742
743 @lilypond[quote,ragged-right]
744 ossia = { f4 f f f }
745 \score{
746   \relative c' \new Staff = "main" {
747     c4 c c c
748     <<
749       \new Staff \with {alignAboveContext=main} \ossia
750       { d8 f d f d f d f }
751     >>
752   }
753 }
754 @end lilypond
755
756
757 @node Explaining the Internals Reference
758 @section Explaining the Internals Reference
759
760
761 @menu
762 * Navigating the program reference::  
763 * Layout interfaces::           
764 * Determining the grob property::  
765 * Naming conventions::          
766 @end menu
767
768 @node Navigating the program reference
769 @subsection Navigating the program reference
770
771 @c TODO remove this (it's in the LM)
772 @c Replace with more factual directions
773
774 Suppose we want to move the fingering indication in the fragment
775 below:
776
777 @lilypond[quote,fragment,relative=2,verbatim]
778 c-2
779 \stemUp
780 f
781 @end lilypond
782
783 If you visit the documentation on fingering instructions (in
784 @ref{Fingering instructions}), you will notice:
785
786 @quotation
787 @strong{See also}
788
789 Internals Reference: @rinternals{Fingering}.
790
791 @end quotation
792
793
794 @c  outdated info; probably will delete.
795 @ignore
796 This fragment points to two parts of the program reference: a page
797 on @code{FingerEvent} and one on @code{Fingering}.
798
799 The page on @code{FingerEvent} describes the properties of the music
800 expression for the input @code{-2}.  The page contains many links
801 forward.  For example, it says
802
803 @quotation
804 Accepted by: @rinternals{Fingering_engraver},
805 @end quotation
806
807 @noindent
808 That link brings us to the documentation for the Engraver, the
809 plug-in, which says
810
811 @quotation
812 This engraver creates the following layout objects: @rinternals{Fingering}.
813 @end quotation
814
815 In other words, once the @code{FingerEvent}s are interpreted, the
816 @code{Fingering_engraver} plug-in will process them.
817 @end ignore
818
819 @ignore
820 @c  I can't figure out what this is supposed to mean.  -gp
821
822 The @code{Fingering_engraver} is also listed to create
823 @rinternals{Fingering} objects,
824
825 @c  old info?  it doesn't make any sense to me with our current docs.
826 This is also the
827 second bit of information listed under @b{See also} in the Notation
828 manual.
829 @end ignore
830
831 @ifnothtml
832 The programmer's reference is available as an HTML document.  It is
833 highly recommended that you read it in HTML form, either online or
834 by downloading the HTML documentation.  This section will be much more
835 difficult to understand if you are using the
836 PDF manual.
837 @end ifnothtml
838
839 Follow the link to @rinternals{Fingering}.  At the top of the
840 page, you will see
841
842 @quotation
843 Fingering objects are created by: @rinternals{Fingering_engraver} and
844 @rinternals{New_fingering_engraver}.
845 @end quotation
846
847 By following related links inside the program reference, we can follow the
848 flow of information within the program:
849
850 @itemize
851
852 @item @rinternals{Fingering}:
853 @rinternals{Fingering} objects are created by:
854 @rinternals{Fingering_engraver}
855
856 @item @rinternals{Fingering_engraver}:
857 Music types accepted: @rinternals{fingering-event}
858
859 @item @rinternals{fingering-event}:
860 Music event type @code{fingering-event} is in Music expressions named
861 @rinternals{FingerEvent}
862 @end itemize
863
864 This path goes against the flow of information in the program: it
865 starts from the output, and ends at the input event.  You could
866 also start at an input event, and read with the flow of
867 information, eventually ending up at the output object(s).
868
869 The program reference can also be browsed like a normal document.  It
870 contains chapters on
871 @ifhtml
872 @rinternals{Music definitions},
873 @end ifhtml
874 @ifnothtml
875 @code{Music definitions}
876 @end ifnothtml
877 on @rinternals{Translation}, and the @rinternals{Backend}.  Every
878 chapter lists all the definitions used and all properties that may be
879 tuned.
880
881
882 @node Layout interfaces
883 @subsection Layout interfaces
884
885 @cindex interface, layout
886 @cindex layout interface
887 @cindex grob
888
889 The HTML page that we found in the previous section describes the
890 layout object called @rinternals{Fingering}.  Such an object is a
891 symbol within the score.  It has properties that store numbers (like
892 thicknesses and directions), but also pointers to related objects.  A
893 layout object is also called a @emph{Grob}, which is short for Graphical
894 Object.  For more details about Grobs, see @rinternals{grob-interface}.
895
896 The page for @code{Fingering} lists the definitions for the
897 @code{Fingering} object.  For example, the page says
898
899 @quotation
900 @code{padding} (dimension, in staff space):
901
902 @code{0.5}
903 @end quotation
904
905 @noindent
906 which means that the number will be kept at a distance of at least 0.5
907 of the note head.
908
909
910 Each layout object may have several functions as a notational or
911 typographical element.  For example, the Fingering object
912 has the following aspects
913
914 @itemize
915 @item
916 Its size is independent of the horizontal spacing, unlike slurs or beams.
917
918 @item
919 It is a piece of text.  Granted, it is usually a very short text.
920
921 @item
922 That piece of text is typeset with a font, unlike slurs or beams.
923
924 @item
925 Horizontally, the center of the symbol should be aligned to the
926 center of the note head.
927
928 @item
929 Vertically, the symbol is placed next to the note and the staff.
930
931 @item
932 The vertical position is also coordinated with other superscript
933 and subscript symbols.
934 @end itemize
935
936 Each of these aspects is captured in so-called @emph{interface}s,
937 which are listed on the @rinternals{Fingering} page at the bottom
938
939 @quotation
940 This object supports the following interfaces:
941 @rinternals{item-interface},
942 @rinternals{self-alignment-interface},
943 @rinternals{side-position-interface}, @rinternals{text-interface},
944 @rinternals{text-script-interface}, @rinternals{font-interface},
945 @rinternals{finger-interface}, and @rinternals{grob-interface}.
946 @end quotation
947
948 Clicking any of the links will take you to the page of the respective
949 object interface.  Each interface has a number of properties.  Some of
950 them are not user-serviceable (@q{Internal properties}), but others
951 can be modified.
952
953 We have been talking of @emph{the} @code{Fingering} object, but actually it
954 does not amount to much.  The initialization file (see
955 @rlearning{Other sources of information})
956 @file{scm/@/define@/-grobs@/.scm} shows the soul of the @q{object},
957
958 @example
959 (Fingering
960   . ((padding . 0.5)
961      (avoid-slur . around)
962      (slur-padding . 0.2)
963      (staff-padding . 0.5)
964      (self-alignment-X . 0)
965      (self-alignment-Y . 0)
966      (script-priority . 100)
967      (stencil . ,ly:text-interface::print)
968      (direction . ,ly:script-interface::calc-direction)
969      (font-encoding . fetaNumber)
970      (font-size . -5)           ; don't overlap when next to heads.
971      (meta . ((class . Item)
972      (interfaces . (finger-interface
973                     font-interface
974                     text-script-interface
975                     text-interface
976                     side-position-interface
977                     self-alignment-interface
978                     item-interface))))))
979 @end example
980
981 @noindent
982 As you can see, the @code{Fingering} object is nothing more than a
983 bunch of variable settings, and the webpage in the Internals Reference
984 is directly generated from this definition.
985
986
987 @node Determining the grob property
988 @subsection Determining the grob property
989
990 @c TODO remove this (it's in the LM)
991 @c Replace with more factual directions
992
993 Recall that we wanted to change the position of the @b{2} in
994
995 @lilypond[quote,fragment,relative=2,verbatim]
996 c-2
997 \stemUp
998 f
999 @end lilypond
1000
1001 Since the @b{2} is vertically positioned next to its note, we have to
1002 meddle with the interface associated with this positioning.  This is
1003 done using @code{side-position-interface}.  The page for this interface
1004 says
1005
1006 @quotation
1007 @code{side-position-interface}
1008
1009 Position a victim object (this one) next to other objects (the
1010 support).  The property @code{direction} signifies where to put the
1011 victim object relative to the support (left or right, up or down?)
1012 @end quotation
1013
1014 @cindex padding
1015 @noindent
1016 Below this description, the variable @code{padding} is described as
1017
1018 @quotation
1019 @table @code
1020 @item padding
1021 (dimension, in staff space)
1022
1023 Add this much extra space between objects that are next to each other.
1024 @end table
1025 @end quotation
1026
1027 By increasing the value of @code{padding}, we can move the
1028 fingering away from the note head.  The following command inserts
1029 3 staff spaces of white
1030 between the note and the fingering:
1031 @example
1032 \once \override Voice.Fingering #'padding = #3
1033 @end example
1034
1035 Inserting this command before the Fingering object is created,
1036 i.e., before @code{c2}, yields the following result:
1037
1038 @lilypond[quote,relative=2,fragment,verbatim]
1039 \once \override Voice.Fingering #'padding = #3
1040 c-2
1041 \stemUp
1042 f
1043 @end lilypond
1044
1045
1046 In this case, the context for this tweak is @code{Voice}.  This
1047 fact can also be deduced from the program reference, for the page for
1048 the @rinternals{Fingering_engraver} plug-in says
1049
1050 @quotation
1051 Fingering_engraver is part of contexts: @dots{} @rinternals{Voice}
1052 @end quotation
1053
1054
1055 @node Naming conventions
1056 @subsection Naming conventions
1057
1058 Another thing that is needed, is an overview of the various naming
1059 conventions: 
1060
1061     scheme functions: lowercase-with-hyphens (incl. one-word
1062 names)
1063     scheme functions: ly:plus-scheme-style
1064     music events, music classes and music properties:
1065 as-scheme-functions
1066     Grob interfaces: scheme-style
1067     backend properties: scheme-style (but X and Y!)
1068     contexts (and MusicExpressions and grobs): Capitalized or
1069 CamelCase
1070     context properties: lowercaseFollowedByCamelCase
1071     engravers:
1072 Capitalized_followed_by_lowercase_and_with_underscores
1073
1074 Which of these are conventions and which are rules?
1075 Which are rules of the underlying language, and which are
1076 LP-specific?
1077
1078
1079 @node Modifying properties
1080 @section Modifying properties
1081
1082 @menu
1083 * Overview of modifying properties::  
1084 * The \set command::            
1085 * The \override command::       
1086 * \set versus \override::       
1087 * Objects connected to the input::  
1088 @end menu
1089
1090
1091 @node Overview of modifying properties
1092 @subsection Overview of modifying properties
1093
1094 Each context is responsible for creating certain types of graphical
1095 objects.  The settings used for printing these objects are also stored by
1096 context.  By changing these settings, the appearance of objects can be
1097 altered.
1098
1099 The syntax for this is
1100
1101 @example
1102 \override @var{context}.@var{name} #'@var{property} = #@var{value}
1103 @end example
1104
1105 Here @var{name} is the name of a graphical object, like
1106 @code{Stem} or @code{NoteHead}, and @var{property} is an internal
1107 variable of the formatting system (@q{grob property} or @q{layout
1108 property}).  The latter is a symbol, so it must be quoted.  The
1109 subsection @ref{Modifying properties}, explains what to fill in
1110 for @var{name}, @var{property}, and @var{value}.  Here we only
1111 discuss the functionality of this command.
1112
1113 The command
1114
1115 @verbatim
1116 \override Staff.Stem #'thickness = #4.0
1117 @end verbatim
1118
1119 @noindent
1120 makes stems thicker (the default is 1.3, with staff line thickness as a
1121 unit).  Since the command specifies @code{Staff} as context, it only
1122 applies to the current staff.  Other staves will keep their normal
1123 appearance.  Here we see the command in action:
1124
1125 @lilypond[quote,verbatim,relative=2,fragment]
1126 c4
1127 \override Staff.Stem #'thickness = #4.0
1128 c4
1129 c4
1130 c4
1131 @end lilypond
1132
1133 The @code{\override} command changes the definition of the @code{Stem}
1134 within the current @code{Staff}.  After the command is interpreted
1135 all stems are thickened.
1136
1137 Analogous to @code{\set}, the @var{context} argument may be left out,
1138 causing the default context @code{Voice} to be used.  Adding
1139 @code{\once} applies the change during one timestep only.
1140
1141 @lilypond[quote,fragment,verbatim,relative=2]
1142 c4
1143 \once \override Stem #'thickness = #4.0
1144 c4
1145 c4
1146 @end lilypond
1147
1148 The @code{\override} must be done before the object is
1149 started.  Therefore, when altering @emph{Spanner} objects such as slurs
1150 or beams, the @code{\override} command must be executed at the moment
1151 when the object is created.  In this example,
1152
1153 @lilypond[quote,fragment,verbatim,relative=2]
1154 \override Slur #'thickness = #3.0
1155 c8[( c
1156 \override Beam #'thickness = #0.6
1157 c8 c])
1158 @end lilypond
1159
1160 @noindent
1161 the slur is fatter but the beam is not.  This is because the command for
1162 @code{Beam} comes after the Beam is started, so it has no effect.
1163
1164 Analogous to @code{\unset}, the @code{\revert} command for a context
1165 undoes an @code{\override} command; like with @code{\unset}, it only
1166 affects settings that were made in the same context.  In other words, the
1167 @code{\revert} in the next example does not do anything.
1168
1169 @example
1170 \override Voice.Stem #'thickness = #4.0
1171 \revert Staff.Stem #'thickness
1172 @end example
1173
1174 Some tweakable options are called @q{subproperties} and reside inside
1175 properties.  To tweak those, use commands of the form
1176
1177 @c leave this as a long long
1178 @example
1179 \override @var{context}.@var{name} #'@var{property} #'@var{subproperty} = #@var{value}
1180 @end example
1181
1182 @noindent
1183 such as
1184
1185 @example
1186 \override Stem #'details #'beamed-lengths = #'(4 4 3)
1187 @end example
1188
1189
1190 @seealso
1191
1192 Internals: @rinternals{OverrideProperty}, @rinternals{RevertProperty},
1193 @rinternals{PropertySet}, @rinternals{Backend}, and
1194 @rinternals{All layout objects}.
1195
1196
1197 @knownissues
1198
1199 The back-end is not very strict in type-checking object properties.
1200 Cyclic references in Scheme values for properties can cause hangs
1201 or crashes, or both.
1202
1203
1204
1205 @node The \set command
1206 @subsection The @code{\set} command
1207
1208 @cindex properties
1209 @funindex \set
1210 @cindex changing properties
1211
1212 Each context can have different @emph{properties}, variables contained
1213 in that context.  They can be changed during the interpretation step.
1214 This is achieved by inserting the @code{\set} command in the music,
1215
1216 @example
1217 \set @var{context}.@var{prop} = #@var{value}
1218 @end example
1219
1220 For example,
1221 @lilypond[quote,verbatim,relative=2,fragment]
1222 R1*2
1223 \set Score.skipBars = ##t
1224 R1*2
1225 @end lilypond
1226
1227 This command skips measures that have no notes.  The result is that
1228 multi-rests are condensed.  The value assigned is a Scheme object.  In
1229 this case, it is @code{#t}, the boolean True value.
1230
1231 If the @var{context} argument is left out, then the current bottom-most
1232 context (typically @code{ChordNames}, @code{Voice}, or
1233 @code{Lyrics}) is used.  In this example,
1234
1235 @lilypond[quote,verbatim,relative=2,fragment]
1236 c8 c c c
1237 \set autoBeaming = ##f
1238 c8 c c c
1239 @end lilypond
1240
1241 @noindent
1242 the @var{context} argument to @code{\set} is left out, so automatic
1243 beaming is switched off in the current @rinternals{Voice}.  Note that
1244 the bottom-most context does not always contain the property that you
1245 wish to change -- for example, attempting to set the @code{skipBars}
1246 property (of the bottom-most context, in this case @code{Voice}) will
1247 have no effect.
1248
1249 @lilypond[quote,verbatim,relative=2,fragment]
1250 R1*2
1251 \set skipBars = ##t
1252 R1*2
1253 @end lilypond
1254
1255 Contexts are hierarchical, so if a bigger context was specified, for
1256 example @code{Staff}, then the change would also apply to all
1257 @code{Voice}s in the current stave.  The change is applied
1258 @q{on-the-fly}, during the music, so that the setting only affects the
1259 second group of eighth notes.
1260
1261 @funindex \unset
1262
1263 There is also an @code{\unset} command,
1264 @example
1265 \unset @var{context}.@var{prop}
1266 @end example
1267
1268 @noindent
1269 which removes the definition of @var{prop}.  This command removes
1270 the definition only if it is set in @var{context}, so
1271
1272 @example
1273 \set Staff.autoBeaming = ##f
1274 @end example
1275
1276 @noindent
1277 introduces a property setting at @code{Staff} level.  The setting also
1278 applies to the current @code{Voice}.  However,
1279
1280 @example
1281 \unset Voice.autoBeaming
1282 @end example
1283
1284 @noindent
1285 does not have any effect.  To cancel this setting, the @code{\unset}
1286 must be specified on the same level as the original @code{\set}.  In
1287 other words, undoing the effect of @code{Staff.autoBeaming = ##f}
1288 requires
1289 @example
1290 \unset Staff.autoBeaming
1291 @end example
1292
1293 Like @code{\set}, the @var{context} argument does not have to be
1294 specified for a bottom context, so the two statements
1295
1296 @example
1297 \set Voice.autoBeaming = ##t
1298 \set autoBeaming = ##t
1299 @end example
1300
1301 @noindent
1302 are equivalent.
1303
1304
1305 @cindex \once
1306 Settings that should only apply to a single time-step can be entered
1307 with @code{\once}, for example in
1308
1309 @lilypond[quote,verbatim,relative=2,fragment]
1310 c4
1311 \once \set fontSize = #4.7
1312 c4
1313 c4
1314 @end lilypond
1315
1316 the property @code{fontSize} is unset automatically after the second
1317 note.
1318
1319 A full description of all available context properties is in the
1320 program reference, see
1321 @ifhtml
1322 @rinternals{Tunable context properties}.
1323 @end ifhtml
1324 @ifnothtml
1325 Translation @expansion{} Tunable context properties.
1326 @end ifnothtml
1327
1328
1329
1330 @node The \override command
1331 @subsection The @code{\override} command
1332
1333 Commands which change output generally look like
1334
1335 @example
1336 \override Voice.Stem #'thickness = #3.0
1337 @end example
1338
1339 @noindent
1340 To construct this tweak we must determine these bits of information:
1341
1342 @itemize
1343 @item the context: here @code{Voice}.
1344 @item the layout object: here @code{Stem}.
1345 @item the layout property: here @code{thickness}.
1346 @item a sensible value: here @code{3.0}.
1347 @end itemize
1348
1349 Some tweakable options are called @q{subproperties} and reside inside
1350 properties.  To tweak those, use commands in the form
1351
1352 @example
1353 \override Stem #'details #'beamed-lengths = #'(4 4 3)
1354 @end example
1355
1356 @cindex internal documentation
1357 @cindex finding graphical objects
1358 @cindex graphical object descriptions
1359 @cindex tweaking
1360 @funindex \override
1361 @cindex internal documentation
1362
1363 For many properties, regardless of the data type of the property, setting the
1364 property to false ( @code{##f} ) will result in turning it off, causing
1365 LilyPond to ignore that property entirely.  This is particularly useful for
1366 turning off grob properties which may otherwise be causing problems.
1367
1368 We demonstrate how to glean this information from the notation manual
1369 and the program reference.
1370
1371
1372 @node \set versus \override
1373 @subsection @code{\set} vs. @code{\override}
1374
1375 We have seen two methods of changing properties: @code{\set} and
1376 @code{\override}.  There are actually two different kinds of
1377 properties.
1378
1379 Contexts can have properties, which are usually named in
1380 @code{studlyCaps}.  They mostly control the translation from
1381 music to notation, eg. @code{localKeySignature} (for determining
1382 whether to print accidentals), @code{measurePosition} (for
1383 determining when to print a bar line).  Context properties can
1384 change value over time while interpreting a piece of music;
1385 @code{measurePosition} is an obvious example of
1386 this.  Context properties are modified with @code{\set}.
1387
1388 There is a special type of context property: the element
1389 description.  These properties are named in @code{StudlyCaps}
1390 (starting with capital letters).  They contain the
1391 @q{default settings} for said graphical object as an
1392 association list.  See @file{scm/@/define@/-grobs@/.scm}
1393 to see what kind of settings there are.  Element descriptions
1394 may be modified with @code{\override}.
1395
1396 @code{\override} is actually a shorthand;
1397
1398 @example
1399 \override @var{context}.@var{name} #'@var{property} = #@var{value}
1400 @end example
1401
1402 @noindent
1403 is more or less equivalent to
1404
1405 @c  leave this long line -gp
1406 @example
1407 \set @var{context}.@var{name} #'@var{property} = #(cons (cons '@var{property} @var{value}) <previous value of @var{context})
1408 @end example
1409
1410 The value of @code{context} (the alist) is used to initialize
1411 the properties of individual grobs.  Grobs also have
1412 properties, named in Scheme style, with
1413 @code{dashed-words}.  The values of grob properties change
1414 during the formatting process: formatting basically amounts
1415 to computing properties using callback functions.
1416
1417 @code{fontSize} is a special property: it is equivalent to
1418 entering @code{\override ... #'font-size} for all pertinent
1419 objects.  Since this is a common change, the special
1420 property (modified with @code{\set}) was created.
1421
1422
1423 @node Objects connected to the input
1424 @subsection Objects connected to the input
1425
1426 TODO: can't use \tweak in a variable
1427
1428 @funindex \tweak
1429
1430 In some cases, it is possible to take a short-cut for tuning graphical
1431 objects.  For objects that result directly from a piece of the input,
1432 you can use the @code{\tweak} function, for example
1433
1434 @lilypond[relative=2,fragment,verbatim,ragged-right]
1435 <
1436   c
1437   \tweak #'color #red d
1438   g
1439   \tweak #'duration-log #1  a
1440 >4-\tweak #'padding #10 -.
1441 @end lilypond
1442
1443 As you can see, properties are set in the objects directly,
1444 without mentioning the grob name or context where this should be
1445 applied.
1446
1447 This technique only works for objects that are directly connected to
1448 an @rinternals{Event} from the input, for example
1449
1450 @itemize
1451 @item note heads, caused by chord-pitch (i.e., notes inside a chord)
1452 @item articulation signs, caused by articulation instructions
1453 @end itemize
1454
1455 It notably does not work for stems and accidentals (these are caused
1456 by note heads, not by music events) or clefs (these are not caused by
1457 music inputs, but rather by the change of a property value).
1458
1459 There are very few objects which are @emph{directly} connected to
1460 output.  A normal note (like @code{c4}) is not directly connected
1461 to output, so
1462
1463 @example
1464 \tweak #'color #red c4
1465 @end example
1466
1467 @noindent
1468 does not change color.  See @ref{Displaying music expressions}, for
1469 details.
1470
1471
1472 @node Useful concepts and properties
1473 @section Useful concepts and properties
1474
1475
1476 @menu
1477 * Input modes::
1478 * Direction and placement::
1479 * Distances and measurements::
1480 * Spanners::
1481 @end menu
1482
1483 @node Input modes
1484 @subsection Input modes
1485
1486 The way in which the notation contained within an input file is
1487 interpreted is determined by the current input mode.
1488
1489 @strong{Chord mode}
1490
1491 This is activated with the @code{\chordmode} command, and causes
1492 input to be interpreted with the syntax of chord notation, see
1493 @ref{Chord notation}.  Chords are rendered as notes on a staff.
1494
1495 Chord mode is also activated with the @code{\chords} command.
1496 This also creates a new @code{ChordNames} context and
1497 causes the following input to be interpreted with the syntax of
1498 chord notation and rendered as chord names in the @code{ChordNames}
1499 context, see @ref{Printing chord names}.
1500
1501 @strong{Drum mode}
1502
1503 This is activated with the @code{\drummode} command, and causes
1504 input to be interpreted with the syntax of drum notation, see
1505 @ref{Basic percussion notation}.
1506
1507 Drum mode is also activated with the @code{\drums} command.
1508 This also creates a new @code{DrumStaff} context and causes the
1509 following input to be interpreted with the syntax of drum notation
1510 and rendered as drum symbols on a drum staff, see @ref{Basic
1511 percussion notation}.
1512
1513 @strong{Figure mode}
1514
1515 This is activated with the @code{\figuremode} command, and causes
1516 input to be interpreted with the syntax of figured bass, see
1517 @ref{Entering figured bass}.
1518
1519 Figure mode is also activated with the @code{\figures} command.
1520 This also creates a new @code{FiguredBass} context and causes the
1521 following input to be interpreted with the figured bass syntax
1522 and rendered as figured bass symbols in the @code{FiguredBass}
1523 context, see @ref{Introduction to figured bass}.
1524
1525 @strong{Fret and tab modes}
1526
1527 There are no special input modes for entering fret and tab symbols.
1528
1529 To create tab diagrams, enter notes or chords in note mode and
1530 render them in a @code{TabStaff} context, see
1531 @ref{Default tablatures}.
1532
1533 To create fret diagrams above a staff, enter them as markup
1534 above the notes using the @code{\fret-diagram} command, see
1535 @ref{Fret diagrams}.
1536
1537 @strong{Lyrics mode}
1538
1539 This is activated with the @code{\lyricmode} command, and causes
1540 input to be interpreted as lyric syllables with optional durations
1541 and associated lyric modifiers, see @ref{Vocal music}.
1542
1543 Lyric mode is also activated with the @code{\addlyrics} command.
1544 This also creates a new @code{Lyrics} context and an implicit
1545 @code{\lyricsto} command which associates the following lyrics
1546 with the preceding music.
1547
1548 @strong{Markup mode}
1549
1550 This is activated with the @code{\markup} command, and causes
1551 input to be interpreted with the syntax of markup, see
1552 @ref{Text markup commands}.
1553
1554 @c silly work-around for texinfo broken-ness
1555 @c (@strong{Note...} causes a spurious cross-reference in Info)
1556 @b{Note mode}
1557
1558 This is the default mode or it may be activated with the
1559 @code{\notemode} command.  Input is interpreted as pitches,
1560 durations, markup, etc and typeset as musical notation on a staff.
1561
1562 It is not normally necessary to specify note mode explicitly, but
1563 it may be useful to do so in certain situations, for example if you
1564 are in lyric mode, chord mode or any other mode and want to insert
1565 something that only can be done with note mode syntax.
1566
1567 For example, to indicate dynamic markings for the verses of a
1568 choral pieces it is necessary to enter note mode to interpret
1569 the markings:
1570
1571 @lilypond[verbatim,relative=2,quote]
1572 { c4 c4 c4 c4 }
1573 \addlyrics {
1574   \notemode{\set stanza = \markup{ \dynamic f 1. } }
1575   To be sung loudly
1576 }
1577 \addlyrics {
1578   \notemode{\set stanza = \markup{ \dynamic p 2. } }
1579   To be sung quietly
1580 }
1581 @end lilypond
1582
1583
1584
1585 @node Direction and placement
1586 @subsection Direction and placement
1587
1588 In typesetting music the direction and placement of many items is
1589 a matter of choice.  For example, the stems of notes can
1590 be directed up or down; lyrics, dynamics, and other expressive
1591 marks may be placed above or below the staff; text may be aligned
1592 left, right or center; etc.  Most of these choices may be left to
1593 be determined automatically by LilyPond, but in some cases it may
1594 be desirable to force a particular direction or placement.
1595
1596 @strong{Default actions}
1597
1598 By default some directions are always up or always down (e.g.
1599 dynamics or fermata), while other things can alternate between
1600 up or down based on the stem direction (like slurs or accents).
1601
1602 @c TODO Add table showing these
1603
1604 @strong{Context layout}
1605
1606 Contexts are positioned in a system from top to bottom in the
1607 order in which they are encountered.  Note, however, that a
1608 context will be created implicitly if a command is encountered
1609 when there is no suitable context available to contain it.
1610
1611 @c TODO Add example ?
1612
1613 The default order in which contexts are laid out can be changed,
1614 see @ref{Aligning contexts}
1615
1616 @strong{Articulation direction indicators}
1617
1618 When adding articulations to notes the direction indicator,
1619 @code{^} (meaning @qq{up}), @code{_} (meaning @qq{down}) or
1620 @code{-} (meaning @qq{use default direction}), can usually be
1621 omitted, in which case @code{-} is assumed.  But a direction
1622 indicator is @strong{always} required before
1623
1624 @itemize
1625 @item @code{\tweak} commands
1626 @item @code{\markup} commands
1627 @item @code{\tag} commands
1628 @item string markups, e.g. -"string"
1629 @item fingering instructions, e.g. @code{-1}
1630 @item articulation shortcuts, e.g. @code{-.}, @code{->}, @code{--}
1631 @end itemize
1632
1633 @strong{The direction property}
1634
1635 The position or direction of many layout objects is controlled
1636 by the @code{direction} property.
1637
1638 The value of the @code{direction} property may be
1639 set to @code{1}, meaning @qq{up} or @qq{above}, or to @code{-1},
1640 meaning @qq{down} or @qq{below}.  The symbols @code{UP} and
1641 @code{DOWN} may be used instead of @code{1} and @code{-1}
1642 respectively.  The default direction may be specified by setting
1643 @code{direction} to @code{0} or @code{CENTER}.  Alternatively,
1644 in many cases predefined commands
1645 exist to specify the direction.  These are all of the form
1646
1647 @noindent
1648 @code{\xxxUp}, @code{xxxDown}, @code{xxxNeutral}
1649
1650 @noindent
1651 where @code{xxxNeutral} means @qq{use the default direction}.
1652 See @rlearning{Within-staff objects}.
1653
1654 In a few cases, arpeggio being the only common example, the value
1655 of the @code{direction} property specifies whether the object
1656 is to be placed to the right or left of the parent object.  In
1657 this case @code{-1} or @code{LEFT} means @qq{to the left} and
1658 @code{1} or @code{RIGHT} means @qq{to the right}.  @code{0}
1659 or @code{CENTER} means @qq{use the default} direction, as before.
1660
1661 @ignore
1662 These all have side-axis set to #X
1663 AmbitusAccidental - direction has no effect
1664 Arpeggio - works
1665 StanzaNumber - not tried
1666 TrillPitchAccidental - not tried
1667 TrillPitchGroup - not tried
1668 @end ignore
1669
1670
1671
1672 @node Distances and measurements
1673 @subsection Distances and measurements
1674
1675 DISCUSS after working on other sections.
1676
1677 TODO: staff spaces.  Maybe move into tweaks?
1678
1679
1680 @node Spanners
1681 @subsection Spanners
1682
1683 Many objects of musical notation extend over several notes or even
1684 several bars.  Examples are crescendi, trills, tuplet brackets, and
1685 volta repeat brackets.  Such objects are called @qq{spanners}, and
1686 have special properties to control their appearance and behaviour.
1687 Some of these properties are common to all spanners; others are
1688 restricted to a sub-set of the spanners.
1689
1690
1691 @node Common properties
1692 @section Common properties
1693
1694 @menu
1695 * Controlling visibility of objects::
1696 * Line styles::
1697 * Rotating objects::
1698 * Aligning objects::
1699 @end menu
1700
1701 @node Controlling visibility of objects
1702 @subsection Controlling visibility of objects
1703
1704 @c FIXME Write this section
1705
1706 @node Line styles
1707 @subsection Line styles
1708
1709 @c TODO: split the following explanations between expressive marks and
1710 @c text-related stuff. Perhaps create a new subsection named
1711 @c "Spanner limits", "Spanner boundaries"? -vv
1712
1713 Some performance indications, e.g., @i{rallentando} and
1714 @i{accelerando} and @i{trills} are written as text and are
1715 extended over many measures with lines, sometimes dotted or wavy.
1716
1717 These all use the same routines as the glissando for drawing the
1718 texts and the lines, and tuning their behavior is therefore also
1719 done in the same way.  It is done with a spanner, and the routine
1720 responsible for drawing the spanners is
1721 @code{ly:line-interface::print}.  This routine determines the
1722 exact location of the two @i{span points} and draws a line in
1723 between, in the style requested.
1724
1725 Here is an example of the different line styles available, and how
1726 to tune them.
1727
1728 @lilypond[relative=2,ragged-right,verbatim,fragment]
1729 d2 \glissando d'2
1730 \once \override Glissando #'style = #'dashed-line
1731 d,2 \glissando d'2
1732 \override Glissando #'style = #'dotted-line
1733 d,2 \glissando d'2
1734 \override Glissando #'style = #'zigzag
1735 d,2 \glissando d'2
1736 \override Glissando #'style = #'trill
1737 d,2 \glissando d'2
1738 @end lilypond
1739
1740 The information that determines the end-points is computed
1741 on-the-fly for every graphic object, but it is possible to
1742 override these. 
1743
1744 @lilypond[relative=2,ragged-right,verbatim,fragment]
1745 e2 \glissando f
1746 \once \override Glissando #'bound-details #'right #'Y = #-2
1747 e2 \glissando f
1748 @end lilypond
1749
1750 The @code{Glissando} object, like any other using the
1751 @code{ly:line-interface::print} routine, carries a nested
1752 association list.  In the above statement, the value for @code{Y}
1753 is set to @code{-2} for the association list corresponding to the
1754 right end point.  Of course, it is also possible to adjust the
1755 left side with @code{left} instead of @code{right}.
1756
1757 If @code{Y} is not set, the value is computed from the vertical
1758 position of right attachment point of the spanner. 
1759
1760 In case of a line break, the values for the span-points are
1761 extended with contents of the @code{left-broken} and
1762 @code{right-broken} sublists, for example
1763
1764 @lilypond[relative=2,ragged-right,verbatim,fragment]
1765 \override Glissando #'breakable = ##T 
1766 \override Glissando #'bound-details #'right-broken #'Y = #-3
1767 c1 \glissando \break
1768 f1
1769 @end lilypond
1770
1771 The following properties can be used for the
1772
1773 @table @code
1774 @item Y
1775 This sets the Y-coordinate of the end point, in staff space.  By
1776 default, it is the center of the bound object, so for a glissando
1777 it points to the vertical center of the note head.
1778
1779 For horizontal spanners, such as text spanner and trill spanners,
1780 it is hardcoded to 0.
1781
1782 @item attach-dir
1783 This determines where the line starts and ends in X-direction,
1784 relative to the bound object.  So, a value of @code{-1} (or
1785 @code{LEFT}) makes the line start/end at the left side of the note
1786 head it is attached to.
1787
1788 @item X
1789 This is the absolute coordinate of the end point.  It is usually
1790 computed on the fly, and there is little use in overriding it. 
1791
1792 @item stencil
1793 Line spanners may have symbols at the beginning or end, which is
1794 contained in this sub-property.  This is for internal use, it is
1795 recommended to use @code{text}.
1796
1797 @item text
1798 This is a markup that is evaluated to yield stencil.  It is used
1799 to put @i{cresc.} and @i{tr} on horizontal spanners.
1800
1801 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
1802 \override TextSpanner #'bound-details #'left #'text
1803    = \markup { \small \bold Slower }
1804 c2\startTextSpan b c a\stopTextSpan
1805 @end lilypond
1806
1807 @item stencil-align-dir-y
1808 @item stencil-offset
1809 Without setting this, the stencil is simply put there at the
1810 end-point, as defined by the @code{X} and @code{Y} sub properties.
1811 Setting either @code{stencil-align-dir-y} or @code{stencil-offset}
1812 will move the symbol at the edge relative to the end point of the
1813 line
1814
1815 @lilypond[relative=1,fragment,verbatim]
1816 \override TextSpanner #'bound-details
1817   #'left #'stencil-align-dir-y = #DOWN
1818 \override TextSpanner #'bound-details
1819   #'right #'stencil-align-dir-y = #UP
1820
1821 \override TextSpanner #'bound-details
1822   #'left #'text = #"gggg"
1823 \override TextSpanner #'bound-details
1824   #'right #'text = #"hhhh"
1825 c4^\startTextSpan c c c \stopTextSpan
1826 @end lilypond
1827
1828 @item arrow
1829 Setting this sub property to @code{#t} produce an arrowhead at the
1830 end of the line.
1831
1832 @item padding
1833 This sub property controls the space between the specified
1834 end-point of the line and the actual end.  Without padding, a
1835 glissando would start and end in the center of each note head.
1836
1837 @end table
1838
1839 @c TODO: Move to 5.4.4
1840
1841 The music function \endSpanners terminates spanners and hairpins
1842 after exactly one note.
1843
1844 @lilypond[verbatim,quote,ragged-right,relative=2,fragment]
1845 \endSpanners
1846 c2 \startTextSpan c2
1847 c2 \< c2
1848 @end lilypond
1849
1850 When using \endSpanners it is not necessary to close
1851 \startTextSpan with \stopTextSpan, nor is it necessary to close
1852 hairpins with \!.
1853
1854
1855
1856 @seealso
1857
1858 Internals Reference: @rinternals{TextSpanner},
1859 @rinternals{Glissando}, @rinternals{VoiceFollower},
1860 @rinternals{TrillSpanner},
1861 @rinternals{line-spanner-interface}.
1862
1863
1864 @node Rotating objects
1865 @subsection Rotating objects
1866
1867 @c FIXME Write this section
1868
1869 @node Aligning objects
1870 @subsection Aligning objects
1871
1872 @c FIXME Write this section
1873
1874
1875 @node Advanced tweaks
1876 @section Advanced tweaks
1877
1878 @menu
1879 * Vertical grouping of grobs::
1880 * Modifying ends of spanners::
1881 * Modifying stencils::
1882 @end menu
1883
1884
1885
1886
1887 @node Vertical grouping of grobs
1888 @subsection Vertical grouping of grobs
1889
1890 @c FIXME Expand this section
1891
1892 The VerticalAlignment and VerticalAxisGroup grobs work together.
1893 VerticalAxisGroup groups together different grobs like Staff, Lyrics,
1894 etc.  VerticalAlignment then vertically aligns the different grobs
1895 grouped together by VerticalAxisGroup.  There is usually only one
1896 VerticalAlignment per score but every Staff, Lyrics, etc. has its own
1897 VerticalAxisGroup.
1898
1899
1900 @node Modifying ends of spanners
1901 @subsection Modifying ends of spanners
1902
1903 @c FIXME Write this section
1904
1905 @node Modifying stencils
1906 @subsection Modifying stencils
1907
1908 @c FIXME Write this section
1909
1910
1911 @node Discussion of specific tweaks
1912 @section Discussion of specific tweaks
1913
1914 @menu
1915 * old Contexts explained::
1916 @end menu
1917
1918
1919 @node old Contexts explained
1920 @subsection old Contexts explained
1921
1922 @c FIXME Delete this section?  It is in LM
1923 @c Or leave heading and go on from LM?
1924
1925 When music is printed, a lot of notational elements must be added to the
1926 output.  For example, compare the input and output of the following example:
1927
1928 @lilypond[quote,verbatim,relative=2,fragment]
1929 cis4 cis2. g4
1930 @end lilypond
1931
1932 The input is rather sparse, but in the output, bar lines, accidentals,
1933 clef, and time signature are added.  LilyPond @emph{interprets} the
1934 input.  During this step, the musical information is inspected in time
1935 order, similar to reading a score from left to right.  While reading
1936 the input, the program remembers where measure boundaries are, and which
1937 pitches require explicit accidentals.  This information can be presented on
1938 several levels.  For example, the effect of an accidental is limited
1939 to a single staff, while a bar line must be synchronized across the
1940 entire score.
1941
1942 Within LilyPond, these rules and bits of information are grouped in
1943 @emph{Contexts}.  Some examples of contexts are @code{Voice},
1944 @code{Staff}, and @code{Score}.  They are hierarchical, for
1945 example: a @code{Staff} can contain many @code{Voice}s, and a
1946 @code{Score} can contain many @code{Staff} contexts.
1947
1948 @quotation
1949 @sourceimage{context-example,5cm,,}
1950 @end quotation
1951
1952 Each context has the responsibility for enforcing some notation rules,
1953 creating some notation objects and maintaining the associated
1954 properties.  For example, the @code{Voice} context may introduce an
1955 accidental and then the @code{Staff} context maintains the rule to
1956 show or suppress the accidental for the remainder of the measure.  The
1957 synchronization of bar lines is handled at @code{Score} context.
1958
1959 However, in some music we may not want the bar lines to be
1960 synchronized -- consider a polymetric score in 4/4 and 3/4 time.  In
1961 such cases, we must modify the default settings of the @code{Score}
1962 and @code{Staff} contexts.
1963
1964 For very simple scores, contexts are created implicitly, and you need
1965 not be aware of them.  For larger pieces, such as anything with more
1966 than one staff, they must be
1967 created explicitly to make sure that you get as many staves as you
1968 need, and that they are in the correct order.  For typesetting pieces
1969 with specialized notation, it can be useful to modify existing or
1970 to define new contexts.
1971
1972
1973 A complete description of all available contexts is in the program
1974 reference, see
1975 @ifhtml
1976 @rinternals{Contexts}.
1977 @end ifhtml
1978 @ifnothtml
1979 Translation @expansion{} Context.
1980 @end ifnothtml
1981
1982 @c [TODO: describe propagation]
1983
1984
1985