]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/user/changing-defaults.itely
* lily/main.cc (main_with_guile): switch debugging.
[lilypond.git] / Documentation / user / changing-defaults.itely
1 @c -*-texinfo-*-
2 @node Changing defaults
3 @chapter Changing defaults
4
5
6 The purpose of LilyPond's design is to provide the finest output
7 quality as a default. Nevertheless, it may happen that you need to
8 change that default layout.  The layout is controlled through a large
9 number of proverbial ``knobs and switches.''  This chapter does not
10 list each and every knob. Rather, it outlines what groups of controls
11 are available, and it explains how to lookup which knob to use for a
12 certain effect.
13
14 The controls are available for tuning are described in a separate
15 document, the @internalsref{Program reference} manual. This manual
16 lists all different variables, functions and options available in
17 LilyPond. It is available as a HTML document, which is available
18 @uref{http://lilypond.org/doc/Documentation/user/out-www/lilypond-internals/,on-line},
19 but is also included with the LilyPond documentation package.
20
21 There are three areas where the default settings may be changed:
22
23 @itemize @bullet
24 @item Output: changing the appearance of individual
25   objects. For example, changing stem directions, or the location of
26   subscripts.
27   
28 @item Context: changing aspects of the translation from music events to
29   notation. For example, giving each staff a separate time signature. 
30   
31 @item Global layout: changing the appearance of the spacing, line
32   breaks and page dimensions.
33 @end itemize
34
35 Then, there are separate systems for typesetting text (like
36 @emph{ritardando}) and selecting different fonts. This chapter also
37 discusses these.
38
39 Internally, LilyPond uses Scheme (a LISP dialect) to provide
40 infrastructure.  Overriding layout decisions in effect accesses the
41 program internals, so it is necessary to learn a (very small) subset
42 of Scheme. That is why this chapter starts with a short tutorial on
43 entering numbers, lists, strings and symbols in Scheme.
44
45
46 @menu
47 * Scheme tutorial::             
48 * Interpretation contexts::     
49 * Tuning output::               
50 * Fonts::                       
51 * Text markup::                 
52 * Global layout::               
53 * Output details::              
54 @end menu
55
56 @node Scheme tutorial
57 @section Scheme tutorial
58
59 @cindex Scheme
60 @cindex GUILE
61 @cindex Scheme, in-line code
62 @cindex accessing Scheme
63 @cindex evaluating Scheme
64 @cindex LISP
65
66 LilyPond uses the Scheme programming language, both as part of the
67 input syntax, and as internal mechanism to glue together modules of
68 the program. This section is a very brief overview of entering data in
69 Scheme.@footnote{If you want to know more about Scheme, see
70 @uref{http://www.schemers.org}.}
71
72 The most basic thing of a language is data: numbers, character
73 strings, lists, etc. Here is a list of data types that are relevant to
74 LilyPond input.
75
76 @table @asis
77 @item Booleans
78   Boolean values are True or False. The Scheme for True is @code{#t}
79   and False is @code{#f}.
80 @item Numbers
81   Numbers are entered in the standard fashion,
82   @code{1} is the (integer) number one, while @code{-1.5} is a
83   floating point number (a non-integer number). 
84 @item Strings
85   Strings are enclosed in double quotes,
86   @example
87     "this is a string"
88   @end example
89
90   Strings may span several lines
91   @example
92     "this
93     is
94     a string"
95   @end example
96
97   Quotation marks and newlines can also be added with so-called escape
98   sequences. The string @code{a said "b"} is entered as
99   @example
100     "a said \"b\""
101   @end example
102
103   Newlines and backslashes are escaped with @code{\n} and @code{\\}
104 respectively.
105 @end table
106
107
108 In a music file, snippets of Scheme code are introduced with the hash
109 mark @code{#}. So, the previous examples translated in LilyPondese are
110
111 @example
112   ##t ##f 
113   #1 #-1.5
114   #"this is a string"
115   #"this
116   is
117   a string"
118 @end example
119
120 For the rest of this section, we will assume that the data is entered
121 in a music file, so we add @code{#}s everywhere.
122
123 Scheme can be used to do calculations. It uses @emph{prefix}
124 syntax. Adding 1 and 2 is written as @code{(+ 1 2)} rather than the
125 traditional 1+2.
126
127 @lisp
128   #(+ 1 2)
129    @result{} #3 
130 @end lisp
131
132 The arrow @result{} shows that the result of evaluating @code{(+ 1 2)}
133 is @code{3}.  Calculations may be nested: the result of a function may
134 be used for another calculation.
135
136 @lisp
137   #(+ 1 (* 3 4))
138    @result{} #(+ 1 12) 
139    @result{} #13
140 @end lisp
141
142 These calculations are examples of evaluations: an expression (like
143 @code{(* 3 4)} is replaced by its value @code{12}. A similar thing
144 happens with variables. After defining a variable  
145
146 @example
147   twelve = #12 
148 @end example
149
150 variables can also be used in expressions, here
151
152 @example
153   twentyFour = #(* 2 twelve) 
154 @end example 
155
156 the number 24 is stored in the variable @code{twentyFour}.
157
158 The @emph{name} of a variable is also an expression, similar to a
159 number or a string. It is entered as
160
161 @example
162   #'twentyFour
163 @end example
164
165 The quote mark @code{'} prevents Scheme interpreter from substituting
166 @code{24} for the @code{twentyFour}. Instead, we get the name
167 @code{twentyFour}.
168
169 This syntax will be used very frequently, since many of the layout
170 tweaks involve assigning (Scheme) values to internal variables, for
171 example
172
173 @example
174   \override Stem #'thickness = #2.6
175 @end example
176
177 This instruction adjusts the appearance of stems. The value @code{2.6}
178 is put into a the @code{thickness} variable of a @code{Stem}
179 object. This makes stems almost twice as thick as their normal size.
180 To distinguish between variables defined in input files (like
181 @code{twentyFour} in the example above), and internal variables, we
182 will call the latter ``properties.'' So, the stem object has a
183 @code{thickness} property.
184
185 Two-dimensional offsets (X and Y coordinates) as well as object sizes
186 (intervals with a left and right point) are entered as @code{pairs}. A
187 pair@footnote{In Scheme terminology, the pair is called @code{cons},
188 and its two elements are called car and cdr respectively.}  is entered
189 as @code{(first . second)}, and like symbols, they must be quoted,
190
191 @example
192   \override TextScript #'extra-offset = #'(1 . 2)  
193 @end example 
194
195 This assigns the pair (1, 2) to @code{extra-offset} variable of the
196 TextScript object. This moves the object 1 staff space to the right,
197 and 2 spaces up.
198
199 The two elements of a pair may be arbitrary values, for example
200
201 @example
202   #'(1 . 2)
203   #'(#t . #f)
204   #'("blah-blah" . 3.14159265)
205 @end example
206
207 A list is entered by enclosing its elements in parentheses, and adding
208 a quote. For example,
209 @example
210   #'(1 2 3)
211   #'(1 2 "string" #f)
212 @end example
213
214 We have been using lists all along.  A calculation, like @code{(+ 1
215 2)} is also a list (containing the symbol @code{+} and the numbers 1
216 and 2). For entering lists, use a quote @code{'} and for
217 calculations, do not use a quote. 
218
219 Inside a quoted list or pair, there is no need to quote anymore.  The
220 following is a pair of symbols, a list of symbols and a list of lists
221 respectively,
222
223 @example
224   #'(stem . head)
225   #'(staff clef key-signature)
226   #'((1) (2))
227 @end example
228
229
230 @node Interpretation contexts
231 @section Interpretation contexts
232
233 When music is printed, a lot of things notation elements must be added
234 to the input, which is often bare bones.  For example, compare the
235 input and output of the following example
236
237 @lilypond[verbatim,relative=2]
238   cis4 cis2. g4
239 @end lilypond
240
241 The input is rather sparse, but in the output, bar lines, accidentals,
242 clef and time signature are added. LilyPond @emph{interprets} the
243 input. During this step, the musical information is inspected in time
244 order, similar to reading a score from left to right. While reading,
245 the program remembers where measure boundaries are, and what pitches
246 need explicit accidentals.
247
248 This is contextual information. and it can be present on several
249 levels.  For example, the effect of an accidental is limited to a
250 single stave, while a bar line must be synchronized across the entire
251 score.  To match this hierarchy, LilyPond's interpretation step is
252 hierarchical.  There are interpretation contexts, like
253 @context{Voice}, Staff and Score, and each level can maintain its own
254 properties.
255
256 Full description of all available contexts is in the program
257 reference, see
258 @ifhtml
259 @internalsref{Contexts}
260 @end ifhtml
261 @ifnothtml 
262 Translation @arrow{} Context.
263 @end ifnothtml
264
265 [TODO: describe propagation]
266
267
268 @menu
269 * Creating contexts::           
270 * Changing context properties on the fly ::  
271 * Modifying context plug-ins::  
272 * Layout tunings within contexts::  
273 * Changing context default settings::  
274 * Defining new  contexts::      
275 * Which properties to change::  
276 @end menu
277
278 @node Creating contexts
279 @subsection Creating contexts
280
281 For scores with only one voice and one staff, correct contexts are
282 created automatically. For more complex scores, it is necessary to
283 instantiate them by hand.  There are three commands to do this.
284
285 The easiest command is @code{\new}, and it also the quickest to type.
286 It is prepended to a  music expression, for example
287
288 @example
289   \new @var{type} @var{music expression}
290 @end example
291
292 @noindent
293 where @var{type} is a context name (like @code{Staff} or
294 @code{Voice}).  This command creates a new context, and starts
295 interpreting @var{music expression} with that.
296
297 A practical application of @code{\new} is a score with many
298 staves. Each part that should be on its own staff, gets a @code{\new
299 Staff}.
300
301 @lilypond[verbatim,relative=2,raggedright]
302   << \new Staff { c4 c }
303      \new Staff { d4 d }
304   >>
305 @end lilypond
306
307 Like @code{\new}, the @code{\context} command also directs a music
308 expression to a context object, but gives the context an extra name. The
309 syntax is
310
311 @example
312   \context @var{type} = @var{id} @var{music}
313 @end example
314
315 This form will search for an existing context of type @var{type}
316 called @var{id}. If that context does not exist yet, it is created.
317 This is useful if the context referred to later on. For example, when
318 setting lyrics the melody is in a named context
319
320 @example
321  \context Voice = "@b{tenor}" @var{music}
322 @end example
323
324 @noindent
325 so the texts can be properly aligned to its notes,
326
327 @example
328 \new Lyrics \lyricsto "@b{tenor}" @var{lyrics} 
329 @end example
330
331 @noindent
332
333 Another possibility is funneling two different music expressions into
334 one context. In the following example, articulations and notes are
335 entered separately,
336
337 @verbatim
338 music = \notes { c4 c4 }
339 arts = \notes  { s4-. s4-> }
340 @end verbatim
341
342 They are combined by sending both to the same @context{Voice} context,
343
344 @verbatim
345   << \new Staff \context Voice = "A" \music
346      \context Voice = "A" \arts
347   >>
348 @end verbatim
349 @lilypond[raggedright]
350 music = \notes { c4 c4 }
351 arts = \notes  { s4-. s4-> }
352 \score {
353        \notes \relative c''  << \new Staff \context Voice = "A" \music
354      \context Voice = "A" \arts
355   >>
356
357 @end lilypond
358
359
360
361 The third command for creating contexts is
362 @example
363   \context @var{type} @var{music}
364 @end example
365
366
367 @noindent
368 This is similar to @code{\context} with @code{= @var{id}}, but matches
369 any context of type @var{type}, regardless of its given name.
370
371 This variant is used with music expressions that can be interpreted at
372 several levels. For example, the @code{\applyoutput} command (see
373 @ref{Running a function on all layout objects}). Without an explicit
374 @code{\context}, it is usually is applied to @context{Voice}
375
376 @example
377   \applyoutput #@var{function}   % apply to Voice
378 @end example
379
380 To have it interpreted at @context{Score} or @context{Staff} level use
381 these forms
382
383 @example
384   \context Score \applyoutput #@var{function}
385   \context Staff \applyoutput #@var{function}
386 @end example
387
388
389 @node Changing context properties on the fly 
390 @subsection Changing context properties  on the fly
391
392 Each context can have different @emph{properties}, variables contained
393 in that context. They can be changed during the interpretation step.
394 This is achieved by inserting the @code{\set} command in the music,
395
396 @quotation
397   @code{\set } @var{context}@code{.}@var{prop}@code{ = #}@var{value} 
398 @end quotation
399
400 For example,
401 @lilypond[verbatim,relative=2]
402   R1*2 
403   \set Score.skipBars = ##t
404   R1*2
405 @end lilypond
406
407 This command skips measures that have no notes. The result is that
408 multi rests are condensed.  The value assigned is a Scheme object. In
409 this case, it is @code{#t}, the boolean True value.
410
411 If the @var{context} argument is left out, then the current bottom-most
412 context (typically @context{ChordNames}, @context{Voice} or
413 @context{Lyrics}) is used.  In this example,
414
415 @lilypond[verbatim,relative=2]
416   c8 c c c
417   \set autoBeaming = ##f
418   c8 c c c
419 @end lilypond
420
421 @noindent
422 the @var{context} argument to @code{\set} is left out, and the current
423 @internalsref{Voice} is used.
424
425 Contexts are hierarchical, so if a bigger context was specified, for
426 example @context{Staff}, then the change would also apply to all
427 @context{Voice}s in the current stave. The change is applied
428 `on-the-fly', during the music, so that the setting only affects the
429 second group of eighth notes.
430
431 There is also an @code{\unset} command,
432 @quotation
433   @code{\set }@var{context}@code{.}@var{prop}
434 @end quotation
435
436 @noindent
437 which removes the definition of @var{prop}. This command only removes
438 the definition if it is set in @var{context}. In
439
440 @example
441   \set Staff.autoBeaming = ##f
442   \unset Voice.autoBeaming
443 @end example
444
445 @noindent
446 the current @context{Voice} does not have the property, and the
447 definition at @context{Staff} level remains intact. Like @code{\set},
448 the @var{context} argument does not have to be specified for a bottom
449 context.
450
451 Settings that should only apply to a single time-step can be entered
452 easily with @code{\once}, for example in
453
454 @lilypond[verbatim,relative=2]
455   c4
456   \once \set fontSize = #4.7
457   c4
458   c4
459 @end lilypond
460
461 the property @code{fontSize} is unset automatically after the second
462 note.
463
464 A full description of all available context properties is in the
465 program reference, see
466 @ifhtml
467 @internalsref{Tunable-context-properties}.
468 @end ifhtml
469 @ifnothtml
470 Translation @arrow{} Tunable context properties.
471 @end ifnothtml
472
473
474 @node Modifying context plug-ins
475 @subsection Modifying context plug-ins
476
477 Notation contexts (like Score and Staff) not only store properties,
478 they also contain plug-ins, called ``engravers'' that create notation
479 elements. For example, the Voice context contains a
480 @code{Note_head_engraver} and the Staff context contains a
481 @code{Key_signature_engraver}.
482
483 For a full a description of each plug-in, see 
484 @ifhtml
485 @internalsref{Engravers}
486 @end ifhtml
487 @ifnothtml
488 Program reference @arrow Translation @arrow{} Engravers.
489 @end ifnothtml
490 Every context described in
491 @ifhtml
492 @internalsref{Contexts}
493 @end ifhtml
494 @ifnothtml 
495 Program reference @arrow Translation @arrow{} Context.
496 @end ifnothtml
497 lists the engravers used for that context.
498
499
500 It can be useful to shuffle around these plug-ins. This is done by
501 starting a new context, with @code{\new} or @code{\context}, and
502 modifying it like this, 
503
504 @example
505  \new @var{context} \with @{
506    \consists @dots{}
507    \consists @dots{}
508    \remove  @dots{}
509    \remove @dots{}
510    @emph{etc.}
511  @}
512  @var{..music..}
513 @end example
514
515 where the @dots{} should be the name of an engraver. Here is a simple
516 example which removes @code{Time_signature_engraver} and
517 @code{Clef_engraver} from a @code{Staff} context,
518
519 @lilypond[relative=1, verbatim]
520 << \new Staff {
521     f2 g
522   }
523   \new Staff \with {
524      \remove "Time_signature_engraver"
525      \remove "Clef_engraver"
526   } {
527     f2 g2
528   }
529 >>
530 @end lilypond
531
532 In the second stave there are no time signature or clef symbols.  This
533 is a rather crude method of making objects disappear, it will affect the
534 entire staff. The spacing will be adversely influenced too. More
535 sophisticated methods of blanking objects are shown in (TODO).
536
537 The next example shows a practical application.  Bar lines and time
538 signatures are normally synchronized across the score.  This is done
539 by the @code{Timing_engraver}. This plug-in keeps an administration of
540 time signature, location within the measure, etc. By moving the
541 @code{Timing_engraver} engraver from Score to Staff context, we can
542 have score where each staff has its own time signature.
543
544 @cindex polymetric scores
545
546
547 @lilypond[relative=1,raggedright,verbatim]
548 \new Score \with {
549   \remove "Timing_engraver"
550 } <<
551   \new Staff \with {
552     \consists "Timing_engraver"
553   } {
554       \time 3/4
555       c4 c c c c c
556   }
557   \new Staff \with {
558     \consists "Timing_engraver"
559   } {
560        \time 2/4
561        c4 c c c c c
562   }
563 >>
564 @end lilypond
565
566
567 @node Layout tunings within contexts
568 @subsection Layout tunings within contexts
569
570 Each context is responsible for creating certain types of graphical
571 objects. The settings used for printing these objects are also stored by
572 context. By changing these settings, the appearance of objects can be
573 altered.
574  
575 The syntax for this is
576
577 @example
578   \override @var{context}.@var{name}@code{ #'}@var{property} = #@var{value}
579 @end example
580
581 Here @var{name} is the name of a graphical object, like @code{Stem} or
582 @code{NoteHead}.  @var{property} is an internal variable of the
583 formatting system (`grob property' or `layout property'). It is a
584 symbol, so it must be quoted. The subsection refTODO explains what to
585 fill in for @var{name}, @var{property} and @var{value}. Here we only
586 discuss functionality of this command.
587
588 The command
589
590 @verbatim
591   \override Staff.Stem #'thickness = #4.0 
592 @end verbatim
593
594 @noindent
595 makes stems thicker (the default is 1.3, with staff line thickness as a
596 unit). Since the command specifies @context{Staff} as context, it only
597 applies to the current staff. Other staves will keep their normal
598 appearance.  Here we see the command in action:
599
600 @lilypond[verbatim,relative=2]
601   c4
602   \override Staff.Stem #'thickness = #4.0 
603   c4
604   c4
605   c4
606 @end lilypond
607
608 The @code{\override} command is executed during the interpreting phase,
609 and changes the definition of the @code{Stem} within
610 @context{Staff}. After the command all stems are thickened.
611
612 Analogous to @code{\set}, the @var{context} argument may be left out,
613 causing it to default to @context{Voice} and adding @code{\once} applies
614 the change during only one timestep
615
616 @lilypond[verbatim,relative=2]
617   c4
618   \once \override Stem #'thickness = #4.0 
619   c4
620   c4 
621 @end lilypond
622
623 The @code{\override} must be done before the object is
624 started. Therefore, when altering @emph{Spanner} objects, like slurs or
625 beams, the @code{\override} command must be executed at the moment that
626 the object is created. In this example,
627
628
629 @lilypond[verbatim,relative=2]
630   \override Slur #'thickness = #3.0
631   c8[( c
632   \override Beam #'thickness = #0.6
633   c8 c]) 
634 @end lilypond
635
636 @noindent
637 the slur is fatter and the beam is not. This is because the command for
638 @code{Beam} comes after the Beam is started. Therefore it has no effect.
639
640 Analogous to @code{\unset}, the @code{\revert} command for a context
641 undoes a @code{\override} command; like with @code{\unset}, it only
642 affects settings that were made in the same context. In other words, the
643 @code{\revert} in the next example does not do anything.
644
645 @verbatim
646   \override Voice.Stem #'thickness = #4.0
647   \revert Staff.Stem #'thickness
648 @end verbatim
649
650
651
652
653 @seealso
654
655 Internals: @internalsref{OverrideProperty}, @internalsref{RevertProperty},
656 @internalsref{PropertySet}, @internalsref{All-backend-properties}, and
657 @internalsref{All-layout-objects}.
658
659
660 @refbugs
661
662 The back-end is not very strict in type-checking object properties.
663 Cyclic references in Scheme values for properties can cause hangs
664 and/or crashes.
665
666
667 @node Changing context default settings
668 @subsection Changing context default settings
669
670 The adjustments of the previous chapters can also be entered separate
671 from the music, in the @code{\paper} block,
672
673 @example
674   \paper @{
675      @dots{}
676      \context @{
677         \StaffContext
678
679         \set fontSize = #-2
680         \override Stem #'thickness
681         \remove "Time_signature_engraver"
682       @}
683    @}
684 @end example
685
686 This
687 @example
688   \StaffContext
689 @end example
690
691 @noindent
692 takes the existing definition @context{Staff} from the identifier
693 @code{StaffContext}. This works analogously other contexts, so the
694 existing definition  of @code{Voice} is in 
695 @code{\VoiceContext}.
696
697 The statements
698 @example
699         \set fontSize = #-2
700         \override Stem #'thickness
701         \remove "Time_signature_engraver"
702 @end example
703
704 @noindent
705 affect all staves in the score.
706
707 The @code{\set} keyword is optional within the @code{\paper} block, so
708
709 @example
710   fontSize = #-2
711 @end example
712
713 @noindent
714 will also work.
715
716
717
718 @refbugs
719
720 It is not possible to collect changes in a variable, and apply them to
721 one @code{\context} definition by referencing that variable.
722
723
724 @node Defining new  contexts
725 @subsection Defining new  contexts
726
727 Specific contexts, like @context{Staff} and @code{Voice} are made of
728 simple building blocks, and it is possible to compose engraver
729 plug-ins in different combinations, thereby creating new types of
730 contexts.
731
732 The next example shows how to build a different type of
733 @context{Voice} context from scratch.  It will be similar to
734 @code{Voice}, but print centered slash noteheads only. It can be used
735 to indicate improvisation in Jazz pieces,
736
737 @lilypond[raggedright]
738   \paper { \context {
739     \name ImproVoice
740     \type "Engraver_group_engraver"
741     \consists "Note_heads_engraver"
742     \consists "Text_engraver"
743     \consists Pitch_squash_engraver
744     squashedPosition = #0
745     \override NoteHead #'style = #'slash
746     \override Stem #'transparent = ##t
747     \alias Voice
748   }
749   \context { \StaffContext
750     \accepts "ImproVoice"
751   }}
752   \score { \notes \relative c'' {
753     a4 d8 bes8 \new ImproVoice { c4^"ad lib" c 
754      c4 c^"undress" c_"while playing :)" c } 
755     a1 
756   }}
757 @end lilypond
758
759
760 These settings are again done within a @code{\context} block inside a
761 @code{\paper} block,
762
763 @example
764   \paper @{
765     \context @{
766       @dots{}
767     @}
768   @}
769 @end example
770
771 In the following discussion, the example input shown should go on the
772 @dots{} of the previous fragment.
773
774 First, name the context gets a name. Instead of @context{Voice} it
775 will be called @context{ImproVoice},
776
777 @verbatim
778   \name ImproVoice
779 @end verbatim
780
781 Since it is similar to the @context{Voice}, we want commands that work
782 on (existing) @context{Voice}s to remain working. This is achieved by
783 giving the new context an alias @context{Voice},
784
785 @verbatim
786   \alias Voice
787 @end verbatim
788
789 The context will print notes, and instructive texts
790
791 @verbatim
792   \consists Note_heads_engraver
793   \consists Text_engraver
794 @end verbatim
795
796 but only on the center line,
797
798 @verbatim
799   \consists Pitch_squash_engraver
800   squashedPosition = #0
801 @end verbatim
802
803 The @internalsref{Pitch_squash_engraver} modifies note heads (created
804 by @internalsref{Note_heads_engraver}) and sets their vertical
805 position to the value of @code{squashedPosition}, in this case
806 @code{0}, the center line.
807
808 The notes look like a  slash, without a stem,
809
810 @verbatim
811     \override NoteHead #'style = #'slash
812     \override Stem #'transparent = ##t
813 @end verbatim
814
815
816 All these plug-ins have to cooperate, and this is achieved with a
817 special plug-in, which must be marked with the keyword @code{\type}.
818 This should always be @internalsref{Engraver_group_engraver},
819
820 @example
821  \type "Engraver_group_engraver"
822 @end example
823
824 Put together, we get
825
826 @verbatim
827   \context {
828     \name ImproVoice
829     \type "Engraver_group_engraver"
830     \consists "Note_heads_engraver"
831     \consists "Text_script_engraver"
832     \consists Pitch_squash_engraver
833     squashedPosition = #0
834     \override NoteHead #'style = #'slash
835     \override Stem #'transparent = ##t
836     \alias Voice
837   }
838 @end verbatim
839
840 Contexts form hierarchies. We want to hang the @context{ImproVoice}
841 under @context{Staff}, just like normal @code{Voice}s. Therefore, we
842 modify the @code{Staff} definition with the @code{\accepts}
843 command,@footnote{The opposite of @code{\accepts} is @code{\denies},
844 which is sometimes when reusing existing context definitions. }
845
846
847
848 @verbatim
849   \context {
850     \StaffContext
851     \accepts ImproVoice    
852   }
853 @end verbatim 
854
855 Putting both into a @code{\paper} block, like
856
857 @example
858   \paper @{
859     \context @{
860       \name ImproVoice
861       @dots{}
862     @}
863   \context @{
864     \StaffContext
865     \accepts "ImproVoice"
866   @}
867 @}
868 @end example
869
870 Then the output at the start of this subsection can be entered as
871
872 @verbatim
873 \score {
874   \notes \relative c'' {
875      a4 d8 bes8
876      \new ImproVoice {
877        c4^"ad lib" c 
878        c4 c^"undress"
879        c c_"while playing :)"
880      }
881      a1 
882   }
883 }
884 @end verbatim
885   
886
887     
888 @node Which properties to change
889 @subsection Which properties to change
890
891
892 There are many different properties.  Not all of them are listed in
893 this manual. However, the program reference lists them all in the
894 section @internalsref{Context-properties}, and most properties are
895 demonstrated in one of the
896 @ifhtml
897 @uref{../../../input/test/out-www/collated-files.html,tips-and-tricks}
898 @end ifhtml
899 @ifnothtml
900 tips-and-tricks
901 @end ifnothtml
902 examples.
903
904
905 @node Tuning output
906 @section Tuning output
907
908 In the previous section, we have already touched on a command that
909 changes layout details, the @code{\override} command. In this section,
910 we will look at in more detail how to use the command in practice.
911 First, we will give a a few versatile commands, which are sufficient
912 for many situations. The next section will discuss general use of
913 @code{\override}.
914
915
916
917 -nmost adjustments simply
918
919
920
921 The commands changes 
922
923
924 There are situations where default layout decisions are not
925 sufficient.  In this section we discuss ways to override these
926 defaults.
927
928 Formatting is internally done by manipulating so called objects
929 (graphic objects). Each object carries with it a set of properties
930 (object or layout properties) specific to that object.  For example, a
931 stem object has properties that specify its direction, length and
932 thickness.
933
934 The most direct way of tuning the output is by altering the values of
935 these properties. There are two ways of doing that: first, you can
936 temporarily change the definition of one type of object, thus
937 affecting a whole set of objects.  Second, you can select one specific
938 object, and set a layout property in that object.
939
940 Do not confuse layout properties with translation
941 properties. Translation properties always use a mixed caps style
942 naming, and are manipulated using @code{\set} and @code{\unset}: 
943 @example
944   \set Context.propertyName = @var{value}
945 @end example
946
947 Layout properties are use Scheme style variable naming, i.e.  lower
948 case words separated with dashes. They are symbols, and should always
949 be quoted using @code{#'}.  For example, this could be an imaginary
950 layout property name:
951 @example
952   #'layout-property-name
953 @end example
954
955
956 @menu
957 * Common tweaks::               
958 * Constructing a tweak::        
959 * Navigating the program reference::  
960 * Layout interfaces::           
961 * Determining the grob property::  
962 @end menu
963
964
965
966 @node Common tweaks
967 @subsection Common tweaks
968
969 Some overrides are so common that predefined commands are provided as
970 a short cut.  For example, @code{\slurUp} and @code{\stemDown}. These
971 commands are described in
972 @ifhtml
973 the
974 @end ifhtml
975 @ref{Notation manual}, under the sections for slurs and stems
976 respectively.
977
978 The exact tuning possibilities for each type of layout object are
979 documented in the program reference of the respective
980 object. However, many layout objects share properties, which can be
981 used to apply generic tweaks.  We mention a couple of these:
982
983 @itemize @bullet
984 @item The @code{extra-offset} property, which
985 @cindex @code{extra-offset}
986 has a pair of numbers as value, moves around objects in the printout.
987 The first number controls left-right movement; a positive number will
988 move the object to the right.  The second number controls up-down
989 movement; a positive number will move it higher.  The units of these
990 offsets are staff-spaces.  The @code{extra-offset} property is a
991 low-level feature: the formatting engine is completely oblivious to
992 these offsets.
993
994 In the following example, the second fingering is moved a little to
995 the left, and 1.8 staff space downwards:
996
997 @cindex setting object properties
998
999 @lilypond[relative=1,verbatim]
1000 \stemUp
1001 f-5
1002 \once \override Fingering
1003     #'extra-offset = #'(-0.3 . -1.8) 
1004 f-5
1005 @end lilypond
1006
1007 @item
1008 Setting the @code{transparent} property will cause an object to be printed
1009 in `invisible ink': the object is not printed, but all its other
1010 behavior is retained. The object still takes up space, it takes part in
1011 collisions, and slurs, and ties and beams can be attached to it.
1012
1013 @cindex transparent objects
1014 @cindex removing objects
1015 @cindex invisible objects
1016 The following example demonstrates how to connect different voices
1017 using ties. Normally, ties only connect two notes in the same
1018 voice. By introducing a tie in a different voice, and blanking a stem
1019 in that voice, the tie appears to cross voices:
1020
1021 @lilypond[fragment,relative=2,verbatim]
1022   << {
1023       \once \override Stem #'transparent = ##t
1024       b8~ b8\noBeam
1025   } \\ {
1026        b[ g8]
1027   } >>
1028 @end lilypond
1029
1030 @item
1031 The @code{padding} property for objects with
1032 @cindex @code{padding}
1033 @code{side-position-interface} can be set to increase distance between
1034 symbols that are printed above or below notes. We only give an
1035 example; a more elaborate explanation is in @ref{Constructing a
1036 tweak}:
1037
1038 @lilypond[relative=1,verbatim]
1039   c2\fermata
1040   \override Script #'padding = #3
1041   b2\fermata
1042 @end lilypond
1043
1044 @end itemize
1045
1046 More specific overrides are also possible.  The following section
1047 discusses in depth how to figure out these statements for yourself.
1048
1049
1050 @node Constructing a tweak
1051 @subsection Constructing a tweak
1052
1053 The general procedure of changing output, that is, entering
1054 a command like
1055
1056 @example
1057         \override Voice.Stem #'thickness = #3.0
1058 @end example
1059
1060 @noindent
1061 means that we have to determine these bits of information:
1062
1063 @itemize
1064 @item The context, here: @context{Voice}.
1065 @item The layout object, here @code{Stem}.
1066 @item The layout property, here @code{thickness}
1067 @item A sensible value, here @code{3.0}
1068 @end itemize  
1069
1070
1071 @cindex internal documentation
1072 @cindex finding graphical objects
1073 @cindex graphical object descriptions 
1074 @cindex tweaking
1075 @cindex @code{\override}
1076 @cindex @code{\set}
1077 @cindex internal documentation
1078
1079 We demonstrate how to glean this information from the notation manual
1080 and the program reference.
1081
1082 The program reference is a set of HTML pages, which is part of the
1083 documentation package. On Unix systems, it is is typically in
1084 @file{/usr/share/doc/lilypond}, if you have them, it is best to
1085 bookmark them in your webbrowser, because you will need them.  They
1086 are also available on the web: go to the
1087 @uref{http://lilypond.org,LilyPond website}, click ``Documentation'',
1088 select the correct version, and then click ``Program reference.''
1089
1090 If you have them, use the local HTML files.  They will load faster,
1091 and they are exactly matched to LilyPond version installed.
1092  
1093
1094
1095 @c  [TODO: revise for new site.]
1096
1097 @node Navigating the program reference
1098 @subsection Navigating the program reference
1099
1100 Suppose we want to move the fingering indication in the fragment
1101 below:
1102
1103 @lilypond[relative=2,verbatim]
1104 c-2
1105 \stemUp
1106 f
1107 @end lilypond
1108
1109 If you visit the documentation of @code{Fingering} (in @ref{Fingering
1110 instructions}), you will notice that there is written:
1111
1112 @quotation
1113 @seealso
1114
1115 Program reference: @internalsref{FingerEvent} and @internalsref{Fingering}.
1116
1117 @end quotation
1118
1119 This  fragments points to two parts of the program reference: a page
1120 on @code{FingerEvent} and @code{Fingering}.
1121
1122 The page on  @code{FingerEvent} describes the properties of the  music
1123 expression for the input @code{-2}. The page contains many links
1124 forward.  For example, it says
1125
1126 @quotation
1127   Accepted by: @internalsref{Fingering_engraver},
1128 @end quotation 
1129
1130 @noindent
1131 That link brings us to the documentation for the Engraver, the
1132 plug-in, which says
1133
1134 @quotation
1135   This engraver creates the following layout objects: @internalsref{Fingering}.
1136 @end quotation
1137
1138 In other words, once the @code{FingerEvent}s are interpreted, the
1139 @code{Fingering_engraver} plug-in will process them.
1140 The @code{Fingering_engraver} is also listed to create
1141 @internalsref{Fingering} objects,
1142
1143
1144   Lo and behold, that is also the
1145 second bit of information listed under @b{See also} in the Notation
1146 manual. By clicking around in the program reference, we can follow the
1147 flow of information within the program, either forward (like we did
1148 here), or backwards, following links like this:
1149
1150 @itemize @bullet
1151
1152 @item @internalsref{Fingering}:
1153   @internalsref{Fingering} objects are created by:
1154   @b{@internalsref{Fingering_engraver}}
1155
1156 @item @internalsref{Fingering_engraver}:
1157 Music types accepted: @b{@internalsref{fingering-event}}
1158 @item @internalsref{fingering-event}:
1159 Music event type @code{fingering-event} is in Music objects of type
1160 @b{@internalsref{FingerEvent}}
1161 @end itemize
1162
1163 This path goes against the flow of information in the program: it
1164 starts from the output, and ends at the input event.
1165
1166 The program reference can also be browsed like a normal document.  It
1167 contains a chapter on @internalsref{Music definitions}, on
1168 @internalsref{Translation}, and the @internalsref{Backend}. Every
1169  chapter lists all the definitions used, and all properties that may
1170  be tuned. 
1171
1172  
1173 @node Layout interfaces
1174 @subsection Layout interfaces
1175
1176 @internalsref{Fingering} is a layout object. Such an object is a
1177 symbol within the score. It has properties, which store numbers (like
1178 thicknesses and directions), but also pointers to related objects.
1179 A layout object is also called @emph{grob},
1180 @cindex grob
1181 which is short for Graphical Object.
1182
1183
1184 The page for @code{Fingering} lists the definitions for the
1185 @code{Fingering} object. For example, the page says
1186
1187 @quotation
1188   @code{padding} (dimension, in staff space):
1189   
1190   @code{0.6}
1191 @end quotation
1192
1193 which means that the number will be kept at a distance of at least 0.6
1194 of the note head.
1195
1196
1197 Each layout object may have several functions as a notational or
1198 typographical element. For example, the Fingering object
1199 has the following aspects
1200
1201 @itemize @bullet
1202 @item Its size is independent of the horizontal spacing, unlike slurs or beams
1203
1204 @item It is a piece of text. Granted, it's usually  a very short text.
1205
1206 @item That piece of text is set in a font, unlike slurs or beams.
1207 @item Horizontally, the center of the symbol should be aligned to the
1208 center of the notehead
1209 @item Vertically, the symbol is placed next to the note and the staff.
1210
1211 @item The
1212  vertical position is also coordinated with other super and subscript
1213 symbols
1214 @end itemize
1215
1216 Each of these aspects is captured in a so-called @emph{interface},
1217 which are listed on the @internalsref{Fingering} page at the bottom
1218
1219 @quotation
1220 This object supports the following interfaces:
1221 @internalsref{item-interface},
1222 @internalsref{self-alignment-interface},
1223 @internalsref{side-position-interface}, @internalsref{text-interface},
1224 @internalsref{text-script-interface}, @internalsref{font-interface},
1225 @internalsref{finger-interface} and @internalsref{grob-interface}
1226 @end quotation
1227
1228 Clicking any of the links will take you to the page of the respective
1229 object interface.  Each interface has a number of properties.  Some of
1230 them are not user-serviceable (``Internal properties''), but others
1231 are.
1232
1233 We have been talking of `the' @code{Fingering} object, but actually it
1234 does  not amount to much. The initialization file
1235 @file{scm/define-grobs.scm} shows the soul of the `object',
1236
1237 @verbatim
1238    (Fingering
1239      . (
1240         (print-function . ,Text_item::print)
1241         (padding . 0.6)
1242         (staff-padding . 0.6)
1243         (self-alignment-X . 0)
1244         (self-alignment-Y . 0)
1245         (script-priority . 100)
1246         (font-encoding . number)
1247         (font-size . -5)
1248         (meta . ((interfaces . (finger-interface font-interface
1249                text-script-interface text-interface
1250                side-position-interface self-alignment-interface
1251                item-interface))))
1252   ))
1253 @end verbatim
1254
1255 as you can see, @code{Fingering} is nothing more than a bunch of
1256 variable settings, and the webpage is directly generated from this
1257 definition.
1258
1259 @node Determining the grob property
1260 @subsection Determining the grob property
1261
1262
1263 Recall that we wanted to change the position of the @b{2} in 
1264
1265 @lilypond[relative=2,verbatim]
1266 c-2
1267 \stemUp
1268 f
1269 @end lilypond
1270
1271 Since the @b{2} is vertically positioned next to its note, we have to
1272 meddle with the interface associated with this positioning. This is
1273 done by @code{side-position-interface}. The page for this interface says
1274
1275 @quotation
1276 @code{side-position-interface}
1277
1278   Position a victim object (this one) next to other objects (the
1279   support).  The property @code{direction} signifies where to put the
1280   victim object relative to the support (left or right, up or down?)
1281 @end quotation
1282
1283 @cindex padding
1284 @noindent
1285 below this description, the variable @code{padding} is described as
1286 @quotation
1287 @table @code
1288 @item padding
1289  (dimension, in staff space)
1290
1291  add this much extra space between objects that are next to each
1292   other. 
1293 @end table
1294 @end quotation
1295
1296 By increasing the value of @code{padding}, we can move away the
1297 fingering.  The following command inserts 3 staff spaces of white
1298 between the note and the fingering:
1299 @example
1300 \once \override Fingering #'padding = #3
1301 @end example
1302
1303 Inserting this command before the Fingering object is created,
1304 i.e. before @code{c2}, yields the following result:
1305
1306 @lilypond[relative=2,fragment,verbatim]
1307 \once \override Fingering
1308     #'padding = #3
1309 c-2
1310 \stemUp
1311 f
1312 @end lilypond
1313
1314
1315 In this case, the context for this tweak is @context{Voice}, which
1316 does not have to be specified for @code{\override}.  This fact can
1317 also be deduced from the program reference, for the page for the
1318 @internalsref{Fingering_engraver} plug-in says
1319
1320 @quotation
1321   Fingering_engraver is part of contexts: @dots{} @b{@internalsref{Voice}}
1322 @end quotation
1323
1324
1325 @node Fonts
1326 @section Fonts
1327
1328 @menu
1329 * Selecting font sizes::        
1330 * Font selection::              
1331 @end menu
1332
1333
1334
1335 @node Selecting font sizes
1336 @subsection Selecting font sizes
1337
1338 The most common thing to change about the appearance of fonts is their
1339 size. The font size of any context can be easily changed by setting
1340 the @code{fontSize} property for that context.  Its value is a number:
1341 negative numbers make the font smaller, positive numbers larger. An
1342 example is given below:
1343 @c
1344 @lilypond[fragment,relative=1,verbatim]
1345   c4 c4 \set fontSize = #-3
1346   f4 g4
1347 @end lilypond
1348 This command will set @code{font-size} (see below) in all layout
1349 objects in the current context. It does not change the size of
1350 variable symbols, such as beams or slurs.
1351
1352 The font size is set by modifying the @code{font-size} property.  Its
1353 value is a number indicating the size relative to the standard size.
1354 Each step up is an increase of approximately 12% of the font size. Six
1355 steps is exactly a factor two. The Scheme function @code{magstep}
1356 converts a @code{font-size} number to a scaling factor.
1357
1358 LilyPond has fonts in different design sizes: the music fonts for
1359 smaller sizes are chubbier, while the text fonts are relatively wider.
1360 Font size changes are achieved by scaling the design size that is
1361 closest to the desired size.
1362
1363 The @code{font-size} mechanism does not work for fonts selected
1364 through @code{font-name}. These may be scaled with
1365 @code{font-magnification}.
1366
1367
1368 One of the uses of @code{fontSize} is to get smaller symbols for cue
1369 notes. An elaborate example of those is in
1370 @inputfileref{input/test,cue-notes.ly}.
1371
1372 @cindex @code{font-style}
1373
1374 @refcommands
1375
1376 The following commands set @code{fontSize} for the current voice.
1377
1378 @cindex @code{\tiny}
1379 @code{\tiny}, 
1380 @cindex @code{\small}
1381 @code{\small}, 
1382 @cindex @code{\normalsize}
1383 @code{\normalsize}.
1384
1385
1386
1387 @cindex magnification
1388 @cindex cue notes
1389
1390
1391 @node Font selection
1392 @subsection Font selection
1393
1394 Font selection for the standard fonts, @TeX{}'s Computer Modern fonts,
1395 can also be adjusted with a more fine-grained mechanism.  By setting
1396 the object properties described below, you can select a different font;
1397 all three mechanisms work for every object that supports
1398 @code{font-interface}:
1399
1400
1401 @itemize @bullet
1402 @item @code{font-encoding}
1403 is a symbol that sets layout of the glyphs. Choices include
1404 @code{text} for normal text, @code{braces} (for piano staff braces),
1405 @code{music} (the standard music font, including ancient glyphs),
1406 @code{dynamic} (for dynamic signs) and @code{number} for the number
1407 font.
1408
1409
1410 @item @code{font-family}
1411  is a symbol indicating the general class of the typeface.  Supported are
1412 @code{roman} (Computer Modern), @code{sans} and @code{typewriter}
1413   
1414 @item @code{font-shape}
1415   is a symbol indicating the shape of the font, there are typically
1416 several font shapes available for each font family. Choices are
1417 @code{italic}, @code{caps} and @code{upright}.
1418
1419 @item @code{font-series}
1420 is a  symbol indicating the series of the font. There are typically several
1421 font series for each font family and shape. Choices are @code{medium}
1422 and @code{bold}. 
1423
1424 @end itemize
1425
1426 Fonts selected in the way sketched above come from a predefined style
1427 sheet.
1428
1429  The font used for printing a object can be selected by setting
1430 @code{font-name}, e.g.
1431 @example
1432   \override Staff.TimeSignature
1433       #'font-name = #"cmr17"
1434 @end example
1435
1436 @noindent
1437 Any font can be used, as long as it is available to @TeX{}. Possible
1438 fonts include foreign fonts or fonts that do not belong to the
1439 Computer Modern font family.  The size of fonts selected in this way
1440 can be changed with the @code{font-magnification} property.  For
1441 example, @code{2.0} blows up all letters by a factor 2 in both
1442 directions.
1443
1444 @cindex font size
1445 @cindex font magnification
1446
1447
1448
1449 @seealso
1450
1451 Init files: @file{ly/declarations-init.ly} contains hints how new
1452 fonts may be added to LilyPond.
1453
1454 @refbugs
1455
1456 No style sheet is provided for other fonts besides the @TeX{}
1457 Computer Modern family.
1458
1459 @cindex font selection
1460 @cindex font magnification
1461 @cindex @code{font-interface}
1462
1463
1464 @node Text markup
1465 @section Text markup
1466 @cindex text markup
1467 @cindex markup text
1468
1469
1470 @cindex typeset text
1471
1472 LilyPond has an internal mechanism to typeset texts. You can access it
1473 with the keyword @code{\markup}. Within markup mode, you can enter texts
1474 similar to lyrics: simply enter them, surrounded by spaces:
1475 @cindex markup
1476
1477 @lilypond[verbatim,fragment,relative=1]
1478  c1^\markup { hello }
1479  c1_\markup { hi there }
1480  c1^\markup { hi \bold there, is \italic anyone home? }
1481 @end lilypond
1482
1483 @cindex font switching
1484
1485 The markup in the example demonstrates font switching commands.  The
1486 command @code{\bold} and @code{\italic} only apply to the first
1487 following word; enclose a set of texts with braces to apply a command
1488 to more words:
1489 @example
1490   \markup @{ \bold @{ hi there @} @}
1491 @end example
1492
1493 @noindent
1494 For clarity, you can also do this for single arguments, e.g.
1495
1496 @verbatim
1497   \markup { is \italic { anyone } home }
1498 @end verbatim
1499
1500 @cindex font size, texts
1501
1502
1503 In markup mode you can compose expressions, similar to mathematical
1504 expressions, XML documents and music expressions.  The braces group
1505 notes into horizontal lines. Other types of lists also exist: you can
1506 stack expressions grouped with @code{<}, and @code{>} vertically with
1507 the command @code{\column}. Similarly, @code{\center-align} aligns
1508 texts by their center lines:
1509
1510 @lilypond[verbatim,fragment,relative=1]
1511  c1^\markup { \column < a bbbb c > }
1512  c1^\markup { \center-align < a bbbb c > }
1513  c1^\markup { \line < a b c > }
1514 @end lilypond
1515
1516
1517 Markups can be stored in variables, and these variables
1518 may be attached to notes, like
1519 @verbatim
1520 allegro = \markup { \bold \large { Allegro } }
1521 \notes { a^\allegro b c d }
1522 @end verbatim
1523
1524
1525 Some objects have alignment procedures of their own, which cancel out
1526 any effects of alignments applied to their markup arguments as a
1527 whole.  For example, the @internalsref{RehearsalMark} is horizontally
1528 centered, so using @code{\mark \markup @{ \left-align .. @}} has no
1529 effect.
1530
1531 Similarly, for moving whole texts over notes with
1532 @code{\raise}, use the following trick:
1533 @example
1534   "" \raise #0.5 raised
1535 @end example
1536
1537 The text @code{raised} is now raised relative to the empty string
1538 @code{""} which is not visible.  Alternatively, complete objects can
1539 be moved with layout properties such as @code{padding} and
1540 @code{extra-offset}.
1541
1542
1543
1544 @seealso
1545
1546 Init files:  @file{scm/new-markup.scm}.
1547
1548
1549 @refbugs
1550
1551 Text layout is ultimately done by @TeX{}, which does kerning of
1552 letters.  LilyPond does not account for kerning, so texts will be
1553 spaced slightly too wide.
1554
1555 Syntax errors for markup mode are confusing.
1556
1557 Markup texts cannot be used in the titling of the @code{\header}
1558 field. Titles are made by La@TeX{}, so La@TeX{} commands should be used
1559 for formatting.
1560
1561
1562
1563 @menu
1564 * Overview of text markup commands::  
1565 @end menu
1566
1567 @node  Overview of text markup commands
1568 @subsection Overview of text markup commands
1569
1570 @include markup-commands.tely
1571
1572
1573 @node Global layout
1574 @section Global layout
1575
1576 The global layout determined by three factors: the page layout, the
1577 line breaks and the spacing. These all influence each other. The
1578 choice of spacing determines how densely each system of music is set,
1579 which influences where line breaks breaks are chosen, and thus
1580 ultimately how many pages a piece of music takes. This section
1581 explains how to tune the algorithm for spacing.
1582
1583 Globally spoken, this procedure happens in three steps: first,
1584 flexible distances (``springs'') are chosen, based on durations. All
1585 possible line breaking combination are tried, and the one with the
1586 best results---a layout that has uniform density and requires as
1587 little stretching or cramping as possible---is chosen. When the score
1588 is processed by @TeX{}, each page is filled with systems, and page breaks
1589 are chosen whenever the page gets full.
1590
1591
1592
1593 @menu
1594 * Setting global staff size::   
1595 * Vertical spacing::            
1596 * Horizontal spacing::          
1597 * Line breaking::               
1598 * Page layout::                 
1599 @end menu
1600
1601
1602 @node Setting global staff size
1603 @subsection Setting global staff size
1604
1605 @cindex font size, setting
1606 @cindex staff size, setting
1607 @cindex @code{paper} file
1608
1609 The Feta font provides musical symbols at eight  different
1610 sizes. Each font is tuned for a different staff size: at smaller sizes
1611 the font gets heavier, to match the relatively heavier staff lines.
1612 The recommended font sizes are listed in the following table:
1613
1614 @multitable @columnfractions  .25 .25 .25 .25
1615
1616 @item @b{font name}
1617 @tab @b{staff height (pt)}
1618 @tab @b{staff height (mm)}
1619 @tab @b{use}
1620
1621 @item feta11
1622 @tab 11.22
1623 @tab 3.9 
1624 @tab pocket scores
1625
1626 @item feta13
1627 @tab 12.60
1628 @tab 4.4
1629 @tab
1630
1631 @item feta14
1632 @tab 14.14
1633 @tab 5.0
1634 @tab 
1635
1636 @item feta16
1637 @tab 15.87
1638 @tab 5.6
1639 @tab 
1640
1641 @item feta18
1642 @tab 17.82
1643 @tab 6.3
1644 @tab song books
1645
1646 @item feta20
1647 @tab 17.82
1648 @tab 7.0
1649 @tab standard parts 
1650
1651 @item feta23
1652 @tab 22.45 
1653 @tab 7.9
1654 @tab 
1655
1656 @item feta20
1657 @tab 25.2 
1658 @tab 8.9
1659 @tab
1660 @c modern rental material  ?
1661
1662 @end multitable
1663
1664 These fonts are available in any sizes. The context property
1665 @code{fontSize} and the layout property @code{staff-space} (in
1666 @internalsref{StaffSymbol}) can be used to tune size for individual
1667 staves. The size of individual staves are relative to the global size,
1668 which can be set   in the following manner:
1669
1670 @example
1671   #(set-global-staff-size 14)
1672 @end example
1673
1674 This sets the global default size to 14pt staff height, and scales all
1675 fonts accordingly.
1676
1677 @seealso
1678
1679 This manual: @ref{Selecting font sizes}.
1680
1681
1682
1683 @menu
1684 * Vertical spacing::            
1685 * Horizontal spacing::          
1686 * Line breaking::               
1687 * Page layout::                 
1688 @end menu
1689
1690 @node Vertical spacing
1691 @subsection Vertical spacing
1692
1693 @cindex vertical spacing
1694 @cindex distance between staves
1695 @cindex staff distance
1696 @cindex between staves, distance
1697 @cindex staves per page
1698 @cindex space between staves
1699
1700 The height of each system is determined automatically by LilyPond, to
1701 keep systems from bumping into each other, some minimum distances are
1702 set.  By changing these, you can put staves closer together, and thus
1703 put more  systems onto one page.
1704
1705 Normally staves are stacked vertically. To make
1706 staves maintain a distance, their vertical size is padded. This is
1707 done with the property @code{minimumVerticalExtent}. It takes a pair
1708 of numbers, so if you want to make it smaller from its, then you could
1709 set
1710 @example
1711   \set Staff.minimumVerticalExtent = #'(-4 . 4)
1712 @end example
1713 This sets the vertical size of the current staff to 4 staff spaces on
1714 either side of the center staff line.  The argument of
1715 @code{minimumVerticalExtent} is interpreted as an interval, where the
1716 center line is the 0, so the first number is generally negative.  The
1717 staff can be made larger at the bottom by setting it to @code{(-6
1718 . 4)}.
1719
1720 The piano staves are handled a little differently: to make cross-staff
1721 beaming work correctly, it is necessary that the distance between staves
1722 is fixed beforehand.  This is also done with a
1723 @internalsref{VerticalAlignment} object, created in
1724 @internalsref{PianoStaff}. In this object the distance between the
1725 staves is fixed by setting @code{forced-distance}. If you want to
1726 override this, use a @code{\context} block as follows:
1727 @example
1728   \paper @{
1729     \context @{
1730       \PianoStaffContext
1731       \override VerticalAlignment #'forced-distance = #9
1732     @}
1733     @dots{}
1734   @}
1735 @end example
1736 This would bring the staves together at a distance of 9 staff spaces,
1737 measured from the center line of each staff.
1738
1739 @seealso
1740
1741 Internals: Vertical alignment of staves is handled by the
1742 @internalsref{VerticalAlignment} object.
1743
1744
1745
1746
1747 @node Horizontal spacing
1748 @subsection Horizontal Spacing
1749
1750 The spacing engine translates differences in durations into
1751 stretchable distances (``springs'') of differing lengths. Longer
1752 durations get more space, shorter durations get less.  The shortest
1753 durations get a fixed amount of space (which is controlled by
1754 @code{shortest-duration-space} in the @internalsref{SpacingSpanner} object). 
1755 The longer the duration, the more space it gets: doubling a
1756 duration adds a fixed amount (this amount is controlled by
1757 @code{spacing-increment}) of space to the note.
1758
1759 For example, the following piece contains lots of half, quarter and
1760 8th notes, the eighth note is followed by 1 note head width (NHW). 
1761 The quarter note is followed by 2 NHW, the half by 3 NHW, etc.
1762 @lilypond[fragment,verbatim,relative=1] c2 c4. c8 c4. c8 c4. c8 c8
1763 c8 c4 c4 c4
1764 @end lilypond
1765
1766 Normally, @code{shortest-duration-space} is set to 1.2, which is the
1767 width of a note head, and @code{shortest-duration-space} is set to
1768 2.0, meaning that the shortest note gets 2 NHW (i.e. 2 times
1769 @code{shortest-duration-space}) of space. For normal notes, this space
1770 is always counted from the left edge of the symbol, so the shortest
1771 notes are generally followed by one NHW of space.
1772
1773 If one would follow the above procedure exactly, then adding a single
1774 32th note to a score that uses 8th and 16th notes, would widen up the
1775 entire score a lot. The shortest note is no longer a 16th, but a 32nd,
1776 thus adding 1 NHW to every note. To prevent this, the
1777 shortest duration for spacing is not the shortest note in the score,
1778 but the most commonly found shortest note.  Notes that are even
1779 shorter this are followed by a space that is proportional to their
1780 duration relative to the common shortest note.  So if we were to add
1781 only a few 16th notes to the example above, they would be followed by
1782 half a NHW:
1783
1784 @lilypond[fragment,verbatim,relative=2]
1785  c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4
1786 @end lilypond
1787
1788 The most common shortest duration is determined as follows: in every
1789 measure, the shortest duration is determined. The most common short
1790 duration, is taken as the basis for the spacing, with the stipulation
1791 that this shortest duration should always be equal to or shorter than
1792 1/8th note. The shortest duration is printed when you run lilypond
1793 with @code{--verbose}.  These durations may also be customized. If you
1794 set the @code{common-shortest-duration} in
1795 @internalsref{SpacingSpanner}, then this sets the base duration for
1796 spacing. The maximum duration for this base (normally 1/8th), is set
1797 through @code{base-shortest-duration}.
1798
1799 @cindex @code{common-shortest-duration}
1800 @cindex @code{base-shortest-duration}
1801 @cindex @code{stem-spacing-correction}
1802 @cindex @code{spacing}
1803
1804 In the introduction it was explained that stem directions influence
1805 spacing. This is controlled with @code{stem-spacing-correction}
1806 property in @internalsref{NoteSpacing}, which are generated for every
1807 @internalsref{Voice} context. The @code{StaffSpacing} object
1808 (generated at @internalsref{Staff} context) contains the same property
1809 for controlling the stem/bar line spacing. The following example
1810 shows these corrections, once with default settings, and once with
1811 exaggerated corrections:
1812
1813 @lilypond
1814     \score { \notes {
1815       c'4 e''4 e'4 b'4 |
1816       b'4 e''4 b'4 e''4|
1817       \override Staff.NoteSpacing   #'stem-spacing-correction
1818    = #1.5
1819       \override Staff.StaffSpacing   #'stem-spacing-correction
1820    = #1.5
1821       c'4 e''4 e'4 b'4 |
1822       b'4 e''4 b'4 e''4|      
1823     }
1824     \paper { raggedright = ##t } }
1825 @end lilypond
1826
1827 @cindex SpacingSpanner, overriding properties
1828
1829 Properties of the  @internalsref{SpacingSpanner} must be overridden
1830 from the @code{\paper} block, since the @internalsref{SpacingSpanner} is
1831 created before any property commands are interpreted.
1832 @example
1833 \paper @{ \context  @{
1834   \ScoreContext
1835   SpacingSpanner \override #'spacing-increment = #3.0
1836 @} @}
1837 @end example
1838
1839
1840 @seealso
1841
1842 Internals: @internalsref{SpacingSpanner}, @internalsref{NoteSpacing},
1843 @internalsref{StaffSpacing}, @internalsref{SeparationItem}, and
1844 @internalsref{SeparatingGroupSpanner}.
1845
1846 @refbugs
1847
1848 Spacing is determined on a score wide basis. If you have a score that
1849 changes its character (measured in durations) halfway during the
1850 score, the part containing the longer durations will be spaced too
1851 widely.
1852
1853 There is no convenient mechanism to manually override spacing.
1854
1855
1856
1857 @menu
1858 * Line breaking::               
1859 * Page layout::                 
1860 @end menu
1861
1862 @node Line breaking
1863 @subsection Line breaking
1864
1865 @cindex line breaks
1866 @cindex breaking lines
1867
1868 Line breaks are normally computed automatically. They are chosen such
1869 that lines look neither cramped nor loose, and that consecutive lines
1870 have similar density.
1871
1872 Occasionally you might want to override the automatic breaks; you can
1873 do this by  specifying @code{\break}. This will force a line break at
1874 this point.  Line breaks can only occur at places where there are bar
1875 lines.  If you want to have a line break where there is no bar line,
1876 you can force an invisible bar line by entering @code{\bar
1877 ""}. Similarly, @code{\noBreak} forbids a line break at a 
1878 point.
1879
1880
1881 @cindex regular line breaks
1882 @cindex four bar music. 
1883
1884 For line breaks at regular intervals  use @code{\break} separated by
1885 skips and repeated with @code{\repeat}:
1886 @example
1887 <<  \repeat unfold 7 @{
1888          s1 \noBreak s1 \noBreak
1889          s1 \noBreak s1 \break  @}
1890    @emph{the real music}
1891 >> 
1892 @end  example
1893
1894 @noindent
1895 This makes the following 28 measures (assuming 4/4 time) be broken every
1896 4 measures, and only there.
1897
1898 @refcommands
1899
1900 @code{\break}, @code{\noBreak}
1901 @cindex @code{\break}
1902 @cindex @code{\noBreak}
1903
1904 @seealso
1905
1906 Internals: @internalsref{BreakEvent}.
1907
1908
1909 @node Page layout
1910 @subsection Page layout
1911
1912 @cindex page breaks
1913 @cindex breaking pages
1914
1915 @cindex @code{indent}
1916 @cindex @code{linewidth}
1917
1918 The most basic settings influencing the spacing are @code{indent} and
1919 @code{linewidth}. They are set in the @code{\paper} block. They
1920 control the indentation of the first line of music, and the lengths of
1921 the lines.
1922
1923 If  @code{raggedright} is set to true in the @code{\paper}
1924 block, then the lines are justified at their natural length. This
1925 useful for short fragments, and for checking how tight the natural
1926 spacing is.
1927
1928 @cindex page layout
1929 @cindex vertical spacing
1930
1931 The page layout process happens outside the LilyPond formatting
1932 engine: variables controlling page layout are passed to the output,
1933 and are further interpreted by @code{lilypond} wrapper program. It
1934 responds to the following variables in the @code{\paper} block.  The
1935 spacing between systems is controlled with @code{interscoreline}, its
1936 default is 16pt.  The distance between the score lines will stretch in
1937 order to fill the full page @code{interscorelinefill} is set to a
1938 positive number.  In that case @code{interscoreline} specifies the
1939 minimum spacing.
1940
1941 @cindex @code{textheight}
1942 @cindex @code{interscoreline}
1943 @cindex @code{interscorelinefill}
1944
1945 If the variable @code{lastpagefill} is defined,
1946 @c fixme: this should only be done if lastpagefill= #t 
1947 systems are evenly distributed vertically on the last page.  This
1948 might produce ugly results in case there are not enough systems on the
1949 last page.  The @command{lilypond-book} command ignores
1950 @code{lastpagefill}.  See @ref{lilypond-book manual} for more
1951 information.
1952
1953 @cindex @code{lastpagefill}
1954
1955 Page breaks are normally computed by @TeX{}, so they are not under
1956 direct control of LilyPond.  However, you can insert a commands into
1957 the @file{.tex} output to instruct @TeX{} where to break pages.  This
1958 is done by setting the @code{between-systems-strings} on the
1959 @internalsref{NonMusicalPaperColumn} where the system is broken.
1960 An example is shown in @inputfileref{input/regression,between-systems.ly}.
1961 The predefined command @code{\newpage} also does this.
1962
1963 @cindex paper size
1964 @cindex page size
1965 @cindex @code{papersize}
1966
1967 To change the paper size, use the following Scheme code:
1968 @example
1969         \paper@{
1970            #(set-paper-size "a4")
1971         @}
1972 @end example
1973
1974
1975 @refcommands
1976
1977 @cindex @code{\newpage}
1978 @code{\newpage}. 
1979
1980
1981 @seealso
1982
1983 In this manual: @ref{Invoking lilypond}.
1984
1985 Examples: @inputfileref{input/regression,between-systems.ly}.
1986
1987 Internals: @internalsref{NonMusicalPaperColumn}.
1988
1989 @refbugs
1990
1991 LilyPond has no concept of page layout, which makes it difficult to
1992 reliably choose page breaks in longer pieces.
1993
1994
1995
1996
1997 @node Output details
1998 @section Output details
1999
2000 The default output format is La@TeX{}, which should be run
2001 through La@TeX{}.  Using the option @option{-f}
2002 (or @option{--format}) other output formats can be selected also, but
2003  none of them work reliably.
2004
2005 Now the music is output system by system (a `system' consists of all
2006 staves belonging together).  From @TeX{}'s point of view, a system is an
2007 @code{\hbox} which contains a lowered @code{\vbox} so that it is centered
2008 vertically on the baseline of the text.  Between systems,
2009 @code{\interscoreline} is inserted vertically to have stretchable space.
2010 The horizontal dimension of the @code{\hbox} is given by the
2011 @code{linewidth} parameter from LilyPond's @code{\paper} block.
2012
2013 After the last system LilyPond emits a stronger variant of
2014 @code{\interscoreline} only if the macro
2015 @code{\lilypondpaperlastpagefill} is not defined (flushing the systems
2016 to the top of the page).  You can avoid that by setting the variable
2017 @code{lastpagefill} in LilyPond's @code{\paper} block.
2018
2019 It is possible to fine-tune the vertical offset further by defining the
2020 macro @code{\lilypondscoreshift}:
2021
2022 @example
2023 \def\lilypondscoreshift@{0.25\baselineskip@}
2024 @end example
2025
2026 @noindent
2027 where @code{\baselineskip} is the distance from one text line to the next.
2028
2029 Here an example how to embed a small LilyPond file @code{foo.ly} into
2030 running La@TeX{} text without using the @code{lilypond-book} script
2031 (@pxref{lilypond-book manual}):
2032
2033 @example
2034 \documentclass@{article@}
2035
2036 \def\lilypondpaperlastpagefill@{@}
2037 \lineskip 5pt
2038 \def\lilypondscoreshift@{0.25\baselineskip@}
2039
2040 \begin@{document@}
2041 This is running text which includes an example music file
2042 \input@{foo.tex@}
2043 right here.
2044 \end@{document@}
2045 @end example
2046
2047 The file @file{foo.tex} has been simply produced with
2048
2049 @example
2050   lilypond-bin foo.ly
2051 @end example
2052
2053 The call to @code{\lineskip} assures that there is enough vertical space
2054 between the LilyPond box and the surrounding text lines.
2055