]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/user/changing-defaults.itely
(lilypond_version_re_str): handle
[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 this 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 explains how to lookup which knob to use for a
12 certain effect.
13
14 The controls available for tuning are described in a separate
15 document, the @internalsref{Program reference} manual. That manual
16 lists all different variables, functions and options available in
17 LilyPond. It is written 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 * File structure::              
49 * Interpretation contexts::     
50 * Tuning output::               
51 * Fonts::                       
52 * Text markup::                 
53 * Global layout::               
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 LilyPond 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). Normally lists are interpreted as calculations, and the Scheme
217 interpreter substitutes the outcome of the calculation. To enter a
218 list, we stop evaluation. This is done by quoting the list with a
219 quote @code{'} symbol.  For calculations, do not use a quote.
220
221 Inside a quoted list or pair, there is no need to quote anymore.  The
222 following is a pair of symbols, a list of symbols and a list of lists
223 respectively,
224
225 @example
226   #'(stem . head)
227   #'(staff clef key-signature)
228   #'((1) (2))
229 @end example
230
231 @node File structure
232 @section File structure
233
234 The following items may be present in a @file{.ly} file at toplevel
235
236 @itemize @bullet
237 @item An output definition, such as @code{\bookpaper}, @code{\midi}
238 and @code{\paper}. Such a definition at toplevel changes the default
239 settings for the block entered.
240
241 @item An @code{\header} block. This sets the global header block. This
242 is the block containing the definitions for book-wide settings, like
243 composer, title, etc. 
244
245 @item An @code{\addquote} statement. See @ref{Quoting other voices}
246 for more information.
247
248 @item A @code{\score} block. This score will be collected with other
249 toplevel scores, and combined as a single @code{\book}.
250
251 This behavior can be changed by setting the variable
252 @code{toplevel-score-handler} at toplevel.  The default handler is
253 defined in the init file @file{scm/lily.scm}.
254
255 @item A @code{\book} block formats the block
256
257 This behavior can be changed by setting the variable
258 @code{toplevel-book-handler} at toplevel.  The default handler is
259 defined in the init file @file{scm/lily.scm}.
260
261
262 @item A compound music expression, such as
263 @example
264   @{ c'4 d' e'2 @}
265 @end example
266
267 This will add the piece in a @code{\score}, and formats it into a
268 single book together with all other toplevel @code{\score}s and music
269 expressions.
270  
271 This behavior can be changed by setting the variable
272 @code{toplevel-music-handler} at toplevel. The default handler is
273 defined in the init file @file{scm/lily.scm}.
274  
275 @end itemize
276
277 The following example shows three things which may be entered at
278 toplevel
279 @verbatim
280    \paper  {
281      % movements are non-justified by default    
282      raggedright = ##t
283    }
284
285    \header {
286       title = "Do-re-mi"
287    }
288    
289    { c'4 d' e2 }
290 @end verbatim
291
292
293 At any point in a file, any of the following lexical instructions can
294 be entered:
295
296 @itemize @bullet
297 @item @code{\version}
298 @item @code{\include}
299 @item @code{\encoding}
300 @item @code{\renameinput}
301 @end itemize 
302
303
304  
305 @node Interpretation contexts
306 @section Interpretation contexts
307
308 When music is printed, a lot of notation elements must be added to the
309 input, which is often bare bones.  For example, compare the input and
310 output of the following example:
311
312 @lilypond[verbatim,relative=2,fragment]
313   cis4 cis2. g4
314 @end lilypond
315
316 The input is rather sparse, but in the output, bar lines, accidentals,
317 clef, and time signature are added. LilyPond @emph{interprets} the
318 input. During this step, the musical information is inspected in time
319 order, similar to reading a score from left to right. While reading,
320 the program remembers where measure boundaries are, and what pitches
321 need explicit accidentals.  This information can be presented on
322 several levels.  For example, the effect of an accidental is limited
323 to a single stave, while a bar line must be synchronized across the
324 entire score.
325
326 Within LilyPond, these rules and bits of information are grouped in
327 so-called Contexts. Examples of context are @context{Voice},
328 @context{Staff}, and @context{Score}.  They are hierarchical, for
329 example, a @context{Staff} can contain many @context{Voice}s, and a
330 @context{Score} can contain many @context{Staff} contexts.
331
332 Each context has the responsibility for enforcing some notation rules,
333 creating some notation objects and maintaining the associated
334 properties.  So, the synchronization of bar lines is handled at
335 @context{Score} context.  The @context{Voice} may introduce an
336 accidentals and then the @context{Staff} context maintains the rule to
337 show or suppress the accidental for the remainder of the measure.
338
339 For simple scores, contexts are created implicitly, and you need not
340 be aware of them. For larger pieces, such as piano music, they must be
341 created explicitly to make sure that you get as many staves as you
342 need, and that they are in the correct order.  For typesetting pieces
343 with specialized notation, it can be useful to modify existing or
344 define new contexts.
345
346
347 Full description of all available contexts is in the program
348 reference, see
349 @ifhtml
350 @internalsref{Contexts}.
351 @end ifhtml
352 @ifnothtml 
353 Translation @arrow{} Context.
354 @end ifnothtml
355
356 @c [TODO: describe propagation]
357
358
359 @menu
360 * Creating contexts::           
361 * Changing context properties on the fly::  
362 * Modifying context plug-ins::  
363 * Layout tunings within contexts::  
364 * Changing context default settings::  
365 * Defining new  contexts::      
366 * Which properties to change::  
367 @end menu
368
369 @node Creating contexts
370 @subsection Creating contexts
371
372 For scores with only one voice and one staff, correct contexts are
373 created automatically. For more complex scores, it is necessary to
374 create them by hand.  There are three commands which do this.
375
376 The easiest command is @code{\new}, and it also the quickest to type.
377 It is prepended to a music expression, for example
378
379 @cindex @code{\new}
380 @cindex new contexts
381 @cindex Context, creating
382
383 @example
384   \new @var{type} @var{music expression}
385 @end example
386
387 @noindent
388 where @var{type} is a context name (like @code{Staff} or
389 @code{Voice}).  This command creates a new context, and starts
390 interpreting @var{music expression} with that.
391
392 A practical application of @code{\new} is a score with many
393 staves. Each part that should be on its own staff, is preceded with 
394 @code{\new Staff}.
395
396 @lilypond[verbatim,relative=2,raggedright,fragment]
397   << \new Staff { c4 c }
398      \new Staff { d4 d }
399   >>
400 @end lilypond
401
402 @cindex @code{\context}
403
404 Like @code{\new}, the @code{\context} command also directs a music
405 expression to a context object, but gives the context an extra name. The
406 syntax is
407
408 @example
409   \context @var{type} = @var{id} @var{music}
410 @end example
411
412 This form will search for an existing context of type @var{type}
413 called @var{id}. If that context does not exist yet, it is created.
414 This is useful if the context is referred to later on. For example, when
415 setting lyrics the melody is in a named context
416
417 @example
418  \context Voice = "@b{tenor}" @var{music}
419 @end example
420
421 @noindent
422 so the texts can be properly aligned to its notes,
423
424 @example
425 \new Lyrics \lyricsto "@b{tenor}" @var{lyrics} 
426 @end example
427
428 @noindent
429
430 Another possibility is funneling two different music expressions into
431 one context. In the following example, articulations and notes are
432 entered separately,
433
434 @verbatim
435 music =  { c4 c4 }
436 arts =  { s4-. s4-> }
437 @end verbatim
438
439 They are combined by sending both to the same @context{Voice} context,
440
441 @verbatim
442   << \new Staff \context Voice = "A" \music
443      \context Voice = "A" \arts
444   >>
445 @end verbatim
446 @lilypond[raggedright]
447 music =  { c4   c4 }
448 arts =   { s4-. s4-> }
449    \relative c''  << \new Staff \context Voice = "A" \music
450      \context Voice = "A" \arts
451   >>
452 @end lilypond
453
454 With this mechanism, it is possible to define an Urtext (original
455 edition), with the option put several distinct articulations on the
456 same notes.
457
458 @cindex @code{\context}
459 @cindex creating contexts
460
461 The third command for creating contexts is
462 @example
463   \context @var{type} @var{music}
464 @end example
465
466
467 @noindent
468 This is similar to @code{\context} with @code{= @var{id}}, but matches
469 any context of type @var{type}, regardless of its given name.
470
471 This variant is used with music expressions that can be interpreted at
472 several levels. For example, the @code{\applyoutput} command (see
473 @ref{Running a function on all layout objects}). Without an explicit
474 @code{\context}, it is usually is applied to @context{Voice}
475
476 @example
477   \applyoutput #@var{function}   % apply to Voice
478 @end example
479
480 To have it interpreted at the @context{Score} or @context{Staff} level use
481 these forms
482
483 @example
484   \context Score \applyoutput #@var{function}
485   \context Staff \applyoutput #@var{function}
486 @end example
487
488
489 @node Changing context properties on the fly
490 @subsection Changing context properties on the fly
491
492 @cindex properties
493 @cindex @code{\set}
494 @cindex changing properties
495
496 Each context can have different @emph{properties}, variables contained
497 in that context. They can be changed during the interpretation step.
498 This is achieved by inserting the @code{\set} command in the music,
499
500 @quotation
501   @code{\set } @var{context}@code{.}@var{prop}@code{ = #}@var{value} 
502 @end quotation
503
504 For example,
505 @lilypond[verbatim,relative=2,fragment]
506   R1*2 
507   \set Score.skipBars = ##t
508   R1*2
509 @end lilypond
510
511 This command skips measures that have no notes. The result is that
512 multi rests are condensed.  The value assigned is a Scheme object. In
513 this case, it is @code{#t}, the boolean True value.
514
515 If the @var{context} argument is left out, then the current bottom-most
516 context (typically @context{ChordNames}, @context{Voice}, or
517 @context{Lyrics}) is used.  In this example,
518
519 @lilypond[verbatim,relative=2,fragment]
520   c8 c c c
521   \set autoBeaming = ##f
522   c8 c c c
523 @end lilypond
524
525 @noindent
526 the @var{context} argument to @code{\set} is left out, and the current
527 @internalsref{Voice} is used.
528
529 Contexts are hierarchical, so if a bigger context was specified, for
530 example @context{Staff}, then the change would also apply to all
531 @context{Voice}s in the current stave. The change is applied
532 `on-the-fly', during the music, so that the setting only affects the
533 second group of eighth notes.
534
535 @cindex @code{\unset} 
536
537 There is also an @code{\unset} command,
538 @quotation
539   @code{\unset }@var{context}@code{.}@var{prop}
540 @end quotation
541
542 @noindent
543 which removes the definition of @var{prop}. This command removes
544 the definition only if it is set in @var{context}. In
545
546 @example
547   \set Staff.autoBeaming = ##f
548   \unset Voice.autoBeaming
549 @end example
550
551 @noindent
552 the current @context{Voice} does not have the property, and the
553 definition at @context{Staff} level remains intact. Like @code{\set},
554 the @var{context} argument does not have to be specified for a bottom
555 context.
556
557 Settings that should only apply to a single time-step can be entered
558 easily with @code{\once}, for example in
559
560 @lilypond[verbatim,relative=2,fragment]
561   c4
562   \once \set fontSize = #4.7
563   c4
564   c4
565 @end lilypond
566
567 the property @code{fontSize} is unset automatically after the second
568 note.
569
570 A full description of all available context properties is in the
571 program reference, see
572 @ifhtml
573 @internalsref{Tunable-context-properties}.
574 @end ifhtml
575 @ifnothtml
576 Translation @arrow{} Tunable context properties.
577 @end ifnothtml
578
579
580 @node Modifying context plug-ins
581 @subsection Modifying context plug-ins
582
583 Notation contexts (like Score and Staff) not only store properties,
584 they also contain plug-ins, called ``engravers'' that create notation
585 elements. For example, the Voice context contains a
586 @code{Note_head_engraver} and the Staff context contains a
587 @code{Key_signature_engraver}.
588
589 For a full a description of each plug-in, see 
590 @ifhtml
591 @internalsref{Engravers}.
592 @end ifhtml
593 @ifnothtml
594 Program reference @arrow Translation @arrow{} Engravers.
595 @end ifnothtml
596 Every context described in
597 @ifhtml
598 @internalsref{Contexts}
599 @end ifhtml
600 @ifnothtml 
601 Program reference @arrow Translation @arrow{} Context.
602 @end ifnothtml
603 lists the engravers used for that context.
604
605
606 It can be useful to shuffle around these plug-ins. This is done by
607 starting a new context, with @code{\new} or @code{\context}, and
608 modifying it like this, 
609
610 @example
611  \new @var{context} \with @{
612    \consists @dots{}
613    \consists @dots{}
614    \remove  @dots{}
615    \remove @dots{}
616    @emph{etc.}
617  @}
618  @var{..music..}
619 @end example
620
621 where the @dots{} should be the name of an engraver. Here is a simple
622 example which removes @code{Time_signature_engraver} and
623 @code{Clef_engraver} from a @code{Staff} context,
624
625 @lilypond[relative=1, verbatim,fragment]
626 << \new Staff {
627     f2 g
628   }
629   \new Staff \with {
630      \remove "Time_signature_engraver"
631      \remove "Clef_engraver"
632   } {
633     f2 g2
634   }
635 >>
636 @end lilypond
637
638 In the second stave there are no time signature or clef symbols.  This
639 is a rather crude method of making objects disappear since it will affect
640 the entire staff. The spacing will be adversely influenced too. A more
641 sophisticated methods of blanking objects is shown in @ref{Common
642 tweaks}.
643
644 The next example shows a practical application.  Bar lines and time
645 signatures are normally synchronized across the score.  This is done
646 by the @code{Timing_engraver}. This plug-in keeps an administration of
647 time signature, location within the measure, etc. By moving the
648 @code{Timing_engraver} engraver from Score to Staff context, we can
649 have a score where each staff has its own time signature.
650
651 @cindex polymetric scores
652
653
654 @lilypond[relative=1,raggedright,verbatim,fragment]
655 \new Score \with {
656   \remove "Timing_engraver"
657 } <<
658   \new Staff \with {
659     \consists "Timing_engraver"
660   } {
661       \time 3/4
662       c4 c c c c c
663   }
664   \new Staff \with {
665     \consists "Timing_engraver"
666   } {
667        \time 2/4
668        c4 c c c c c
669   }
670 >>
671 @end lilypond
672
673
674 @node Layout tunings within contexts
675 @subsection Layout tunings within contexts
676
677 Each context is responsible for creating certain types of graphical
678 objects. The settings used for printing these objects are also stored by
679 context. By changing these settings, the appearance of objects can be
680 altered.
681  
682 The syntax for this is
683
684 @example
685   \override @var{context}.@var{name}@code{ #'}@var{property} = #@var{value}
686 @end example
687
688 Here @var{name} is the name of a graphical object, like @code{Stem} or
689 @code{NoteHead}, and @var{property} is an internal variable of the
690 formatting system (`grob property' or `layout property'). The latter is a
691 symbol, so it must be quoted. The subsection @ref{Constructing a
692 tweak} explains what to fill in for @var{name}, @var{property}, and
693 @var{value}. Here we only discuss functionality of this command.
694
695 The command
696
697 @verbatim
698   \override Staff.Stem #'thickness = #4.0 
699 @end verbatim
700
701 @noindent
702 makes stems thicker (the default is 1.3, with staff line thickness as a
703 unit). Since the command specifies @context{Staff} as context, it only
704 applies to the current staff. Other staves will keep their normal
705 appearance.  Here we see the command in action:
706
707 @lilypond[verbatim,relative=2,fragment]
708   c4
709   \override Staff.Stem #'thickness = #4.0 
710   c4
711   c4
712   c4
713 @end lilypond
714
715 The @code{\override} command is executed during the interpreting phase,
716 and changes the definition of the @code{Stem} within
717 @context{Staff}. After the command all stems are thickened.
718
719 Analogous to @code{\set}, the @var{context} argument may be left out,
720 causing it to default to @context{Voice}, and adding @code{\once} applies
721 the change during one timestep only 
722
723 @lilypond[fragment,verbatim,relative=2]
724   c4
725   \once \override Stem #'thickness = #4.0 
726   c4
727   c4 
728 @end lilypond
729
730 The @code{\override} must be done before the object is
731 started. Therefore, when altering @emph{Spanner} objects, like slurs or
732 beams, the @code{\override} command must be executed at the moment when
733 the object is created. In this example,
734
735
736 @lilypond[fragment,verbatim,relative=2]
737   \override Slur #'thickness = #3.0
738   c8[( c
739   \override Beam #'thickness = #0.6
740   c8 c]) 
741 @end lilypond
742
743 @noindent
744 the slur is fatter and the beam is not. This is because the command for
745 @code{Beam} comes after the Beam is started. Therefore it has no effect.
746
747 Analogous to @code{\unset}, the @code{\revert} command for a context
748 undoes a @code{\override} command; like with @code{\unset}, it only
749 affects settings that were made in the same context. In other words, the
750 @code{\revert} in the next example does not do anything.
751
752 @verbatim
753   \override Voice.Stem #'thickness = #4.0
754   \revert Staff.Stem #'thickness
755 @end verbatim
756
757
758
759
760 @seealso
761
762 Internals: @internalsref{OverrideProperty}, @internalsref{RevertProperty},
763 @internalsref{PropertySet}, @internalsref{All-backend-properties}, and
764 @internalsref{All-layout-objects}.
765
766
767 @refbugs
768
769 The back-end is not very strict in type-checking object properties.
770 Cyclic references in Scheme values for properties can cause hangs
771 or crashes, or both.
772
773
774 @node Changing context default settings
775 @subsection Changing context default settings
776
777 The adjustments of the previous chapters can also be entered separate
778 from the music, in the @code{\paper} block,
779
780 @example
781   \paper @{
782      @dots{}
783      \context @{
784         \Staff
785
786         \set fontSize = #-2
787         \override Stem #'thickness
788         \remove "Time_signature_engraver"
789       @}
790    @}
791 @end example
792
793 Here
794 @example
795   \Staff
796 @end example
797
798 @noindent
799 takes the existing definition @context{Staff} from the identifier
800 @code{Staff}. This works analogously to other contexts.
801
802 The statements
803 @example
804         \set fontSize = #-2
805         \override Stem #'thickness
806         \remove "Time_signature_engraver"
807 @end example
808
809 @noindent
810 affect all staves in the score.
811
812 The @code{\set} keyword is optional within the @code{\paper} block, so
813
814 @example
815   fontSize = #-2
816 @end example
817
818 @noindent
819 will also work.
820
821
822
823 @refbugs
824
825 It is not possible to collect changes in a variable, and apply them to
826 one @code{\context} definition by referring to that variable.
827
828
829 @node Defining new  contexts
830 @subsection Defining new  contexts
831
832 Specific contexts, like @context{Staff} and @code{Voice}, are made of
833 simple building blocks, and it is possible to compose engraver
834 plug-ins in different combinations, thereby creating new types of
835 contexts.
836
837 The next example shows how to build a different type of
838 @context{Voice} context from scratch.  It will be similar to
839 @code{Voice}, but print centered slash noteheads only. It can be used
840 to indicate improvisation in Jazz pieces,
841
842 @lilypond[raggedright]
843   \paper { \context {
844     \name ImproVoice
845     \type "Engraver_group_engraver"
846     \consists "Note_heads_engraver"
847     \consists "Text_engraver"
848     \consists Pitch_squash_engraver
849     squashedPosition = #0
850     \override NoteHead #'style = #'slash
851     \override Stem #'transparent = ##t
852     \alias Voice
853   }
854   \context { \Staff
855     \accepts "ImproVoice"
856   }}
857
858
859 \relative c'' {
860     a4 d8 bes8 \new ImproVoice { c4^"ad lib" c 
861      c4 c^"undress" c_"while playing :)" c } 
862     a1 
863 }
864 @end lilypond
865
866
867 These settings are again done within a @code{\context} block inside a
868 @code{\paper} block,
869
870 @example
871   \paper @{
872     \context @{
873       @dots{}
874     @}
875   @}
876 @end example
877
878 In the following discussion, the example input shown should go on the
879 @dots{} in the previous fragment.
880
881 First, name the context gets a name. Instead of @context{Voice} it
882 will be called @context{ImproVoice},
883
884 @verbatim
885   \name ImproVoice
886 @end verbatim
887
888 Since it is similar to the @context{Voice}, we want commands that work
889 on (existing) @context{Voice}s to remain working. This is achieved by
890 giving the new context an alias @context{Voice},
891
892 @verbatim
893   \alias Voice
894 @end verbatim
895
896 The context will print notes, and instructive texts
897
898 @verbatim
899   \consists Note_heads_engraver
900   \consists Text_engraver
901 @end verbatim
902
903 but only on the center line,
904
905 @verbatim
906   \consists Pitch_squash_engraver
907   squashedPosition = #0
908 @end verbatim
909
910 The @internalsref{Pitch_squash_engraver} modifies note heads (created
911 by @internalsref{Note_heads_engraver}) and sets their vertical
912 position to the value of @code{squashedPosition}, in this case
913 @code{0}, the center line.
914
915 The notes look like a  slash, without a stem,
916
917 @verbatim
918     \override NoteHead #'style = #'slash
919     \override Stem #'transparent = ##t
920 @end verbatim
921
922
923 All these plug-ins have to cooperate, and this is achieved with a
924 special plug-in, which must be marked with the keyword @code{\type}.
925 This should always be @internalsref{Engraver_group_engraver},
926
927 @example
928  \type "Engraver_group_engraver"
929 @end example
930
931 Putting together, we get
932
933 @verbatim
934   \context {
935     \name ImproVoice
936     \type "Engraver_group_engraver"
937     \consists "Note_heads_engraver"
938     \consists "Text_script_engraver"
939     \consists Pitch_squash_engraver
940     squashedPosition = #0
941     \override NoteHead #'style = #'slash
942     \override Stem #'transparent = ##t
943     \alias Voice
944   }
945 @end verbatim
946
947 Contexts form hierarchies. We want to hang the @context{ImproVoice}
948 under @context{Staff}, just like normal @code{Voice}s. Therefore, we
949 modify the @code{Staff} definition with the @code{\accepts}
950 command,@footnote{The opposite of @code{\accepts} is @code{\denies},
951 which is sometimes when reusing existing context definitions. }
952
953
954
955 @verbatim
956   \context {
957     \Staff
958     \accepts ImproVoice    
959   }
960 @end verbatim 
961
962 Putting both into a @code{\paper} block, like
963
964 @example
965   \paper @{
966     \context @{
967       \name ImproVoice
968       @dots{}
969     @}
970   \context @{
971     \Staff
972     \accepts "ImproVoice"
973   @}
974 @}
975 @end example
976
977 Then the output at the start of this subsection can be entered as
978
979 @verbatim
980 \relative c'' {
981      a4 d8 bes8
982      \new ImproVoice {
983        c4^"ad lib" c 
984        c4 c^"undress"
985        c c_"while playing :)"
986      }
987      a1
988 }
989 @end verbatim
990   
991
992     
993 @node Which properties to change
994 @subsection Which properties to change
995
996
997 There are many different properties.  Not all of them are listed in
998 this manual. However, the program reference lists them all in the
999 section @internalsref{Tunable-context-properties}, and most properties
1000 are demonstrated in one of the
1001 @ifhtml
1002 @uref{../../../../input/test/out-www/collated-files.html,tips-and-tricks}
1003 @end ifhtml
1004 @ifnothtml
1005 tips-and-tricks
1006 @end ifnothtml
1007 examples.
1008
1009
1010 @node Tuning output
1011 @section Tuning output
1012
1013 In the previous section, we have already touched on a command that
1014 changes layout details, the @code{\override} command. In this section,
1015 we will look at in more detail how to use the command in practice.
1016 First, we will give a a few versatile commands, which are sufficient
1017 for many situations. The next section will discuss general use of
1018 @code{\override}.
1019
1020 @ignore
1021 There are situations where default layout decisions are not
1022 sufficient.  In this section we discuss ways to override these
1023 defaults.
1024
1025 Formatting is internally done by manipulating so called objects
1026 (graphic objects). Each object carries with it a set of properties
1027 (object or layout properties) specific to the object.  For example, a
1028 stem object has properties that specify its direction, length, and
1029 thickness.
1030
1031 The most direct way of tuning the output is to alter the values of
1032 these properties. There are two ways of doing that: First, you can
1033 temporarily change the definition of one type of object, thus
1034 affecting a whole set of objects.  Second, you can select one specific
1035 object, and set a layout property in that object.
1036
1037 Do not confuse layout properties with translation
1038 properties. Translation properties always use a mixed caps style
1039 naming, and are manipulated using @code{\set} and @code{\unset}: 
1040 @example
1041   \set Context.propertyName = @var{value}
1042 @end example
1043
1044 Layout properties are use Scheme style variable naming, i.e.  lower
1045 case words separated with dashes. They are symbols, and should always
1046 be quoted using @code{#'}.  For example, this could be an imaginary
1047 layout property name:
1048 @example
1049   #'layout-property-name
1050 @end example
1051
1052 @end ignore
1053
1054 @menu
1055 * Common tweaks::               
1056 * Constructing a tweak::        
1057 * Navigating the program reference::  
1058 * Layout interfaces::           
1059 * Determining the grob property::  
1060 * Difficult tweaks::            
1061 @end menu
1062
1063
1064
1065 @node Common tweaks
1066 @subsection Common tweaks
1067
1068 Some overrides are so common that predefined commands are provided as
1069 a short-cut, for example, @code{\slurUp} and @code{\stemDown}. These
1070 commands are described in
1071 @ifhtml
1072 the
1073 @end ifhtml
1074 @ref{Notation manual}, under the sections for slurs and stems
1075 respectively.
1076
1077 The exact tuning possibilities for each type of layout object are
1078 documented in the program reference of the respective
1079 object. However, many layout objects share properties, which can be
1080 used to apply generic tweaks.  We mention a few of these:
1081
1082 @itemize @bullet
1083 @item The @code{extra-offset} property, which
1084 @cindex @code{extra-offset}
1085 has a pair of numbers as value, moves around objects in the printout.
1086 The first number controls left-right movement; a positive number will
1087 move the object to the right.  The second number controls up-down
1088 movement; a positive number will move it higher.  The units of these
1089 offsets are staff-spaces.  The @code{extra-offset} property is a
1090 low-level feature: the formatting engine is completely oblivious to
1091 these offsets.
1092
1093 In the following example, the second fingering is moved a little to
1094 the left, and 1.8 staff space downwards:
1095
1096 @cindex setting object properties
1097
1098 @lilypond[fragment,relative=1,verbatim]
1099 \stemUp
1100 f-5
1101 \once \override Fingering
1102     #'extra-offset = #'(-0.3 . -1.8) 
1103 f-5
1104 @end lilypond
1105
1106 @item
1107 Setting the @code{transparent} property will cause an object to be printed
1108 in `invisible ink': the object is not printed, but all its other
1109 behavior is retained. The object still takes up space, it takes part in
1110 collisions, and slurs, and ties and beams can be attached to it.
1111
1112 @cindex transparent objects
1113 @cindex removing objects
1114 @cindex hiding objects
1115 @cindex invisible objects
1116 The following example demonstrates how to connect different voices
1117 using ties. Normally, ties only connect two notes in the same
1118 voice. By introducing a tie in a different voice,
1119
1120 @lilypond[fragment,relative=2]
1121   << {
1122       b8~ b8\noBeam
1123   } \\ {
1124        b[ g8]
1125   } >>
1126 @end lilypond
1127
1128 @noindent
1129 and blanking a stem in that voice, the tie appears to cross voices:
1130
1131 @lilypond[fragment,relative=2,verbatim]
1132   << {
1133       \once \override Stem #'transparent = ##t
1134       b8~ b8\noBeam
1135   } \\ {
1136        b[ g8]
1137   } >>
1138 @end lilypond
1139
1140 @item
1141 The @code{padding} property for objects with
1142 @cindex @code{padding}
1143 @code{side-position-interface} can be set to increase distance between
1144 symbols that are printed above or below notes. We only give an
1145 example; a more elaborate explanation is in @ref{Constructing a
1146 tweak}:
1147
1148 @lilypond[fragment,relative=1,verbatim]
1149   c2\fermata
1150   \override Script #'padding = #3
1151   b2\fermata
1152 @end lilypond
1153
1154 @end itemize
1155
1156 More specific overrides are also possible.  The next section
1157 discusses in depth how to figure out these statements for yourself.
1158
1159
1160 @node Constructing a tweak
1161 @subsection Constructing a tweak
1162
1163 The general procedure of changing output, that is, entering
1164 a command like
1165
1166 @example
1167         \override Voice.Stem #'thickness = #3.0
1168 @end example
1169
1170 @noindent
1171 means that we have to determine these bits of information:
1172
1173 @itemize
1174 @item the context: here @context{Voice}.
1175 @item the layout object: here @code{Stem}.
1176 @item the layout property: here @code{thickness}
1177 @item a sensible value: here @code{3.0}
1178 @end itemize  
1179
1180
1181 @cindex internal documentation
1182 @cindex finding graphical objects
1183 @cindex graphical object descriptions 
1184 @cindex tweaking
1185 @cindex @code{\override}
1186 @cindex @code{\set}
1187 @cindex internal documentation
1188
1189 We demonstrate how to glean this information from the notation manual
1190 and the program reference.
1191
1192 The program reference is a set of HTML pages, which is part of the
1193 documentation package. On Unix systems, it is typically in
1194 @file{/usr/share/doc/lilypond}. If you have them, it is best to
1195 bookmark them in your webbrowser, because you will need them.  They
1196 are also available on the web: go to the
1197 @uref{http://lilypond.org,LilyPond website}, click ``Documentation'',
1198 select the correct version, and then click ``Program reference.''
1199
1200 If you have them, use the local HTML files.  They will load faster,
1201 and they are exactly matched to LilyPond version installed.
1202  
1203
1204 @node Navigating the program reference
1205 @subsection Navigating the program reference
1206
1207 Suppose we want to move the fingering indication in the fragment
1208 below:
1209
1210 @lilypond[fragment,relative=2,verbatim]
1211 c-2
1212 \stemUp
1213 f
1214 @end lilypond
1215
1216 If you visit the documentation of @code{Fingering} (in @ref{Fingering
1217 instructions}), you will notice that there is written:
1218
1219 @quotation
1220 @seealso
1221
1222 Program reference: @internalsref{FingerEvent} and @internalsref{Fingering}.
1223
1224 @end quotation
1225
1226 This  fragments points to two parts of the program reference: a page
1227 on @code{FingerEvent} and on @code{Fingering}.
1228
1229 The page on  @code{FingerEvent} describes the properties of the  music
1230 expression for the input @code{-2}. The page contains many links
1231 forward.  For example, it says
1232
1233 @quotation
1234   Accepted by: @internalsref{Fingering_engraver},
1235 @end quotation 
1236
1237 @noindent
1238 That link brings us to the documentation for the Engraver, the
1239 plug-in, which says
1240
1241 @quotation
1242   This engraver creates the following layout objects: @internalsref{Fingering}.
1243 @end quotation
1244
1245 In other words, once the @code{FingerEvent}s are interpreted, the
1246 @code{Fingering_engraver} plug-in will process them.
1247 The @code{Fingering_engraver} is also listed to create
1248 @internalsref{Fingering} objects,
1249
1250
1251   Lo and behold, that is also the
1252 second bit of information listed under @b{See also} in the Notation
1253 manual. By clicking around in the program reference, we can follow the
1254 flow of information within the program, either forward (like we did
1255 here), or backwards, following links like this:
1256
1257 @itemize @bullet
1258
1259 @item @internalsref{Fingering}:
1260   @internalsref{Fingering} objects are created by:
1261   @b{@internalsref{Fingering_engraver}}
1262
1263 @item @internalsref{Fingering_engraver}:
1264 Music types accepted: @b{@internalsref{fingering-event}}
1265 @item @internalsref{fingering-event}:
1266 Music event type @code{fingering-event} is in Music objects of type
1267 @b{@internalsref{FingerEvent}}
1268 @end itemize
1269
1270 This path goes against the flow of information in the program: it
1271 starts from the output, and ends at the input event.
1272
1273 The program reference can also be browsed like a normal document.  It
1274 contains a chapter on
1275 @ifhtml
1276 @internalsref{Music-definitions},
1277 @end ifhtml
1278 @ifnothtml
1279 Music definitions
1280 @end ifnothtml
1281 on @internalsref{Translation}, and the @internalsref{Backend}. Every
1282 chapter lists all the definitions used, and all properties that may be
1283 tuned.
1284
1285  
1286 @node Layout interfaces
1287 @subsection Layout interfaces
1288
1289 @internalsref{Fingering} is a layout object. Such an object is a
1290 symbol within the score. It has properties, which store numbers (like
1291 thicknesses and directions), but also pointers to related objects.
1292 A layout object is also called @emph{grob},
1293 @cindex grob
1294 which is short for Graphical Object.
1295
1296
1297 The page for @code{Fingering} lists the definitions for the
1298 @code{Fingering} object. For example, the page says
1299
1300 @quotation
1301   @code{padding} (dimension, in staff space):
1302   
1303   @code{0.6}
1304 @end quotation
1305
1306 which means that the number will be kept at a distance of at least 0.6
1307 of the note head.
1308
1309
1310 Each layout object may have several functions as a notational or
1311 typographical element. For example, the Fingering object
1312 has the following aspects
1313
1314 @itemize @bullet
1315 @item Its size is independent of the horizontal spacing, unlike slurs or beams
1316
1317 @item It is a piece of text. Granted, it's usually  a very short text.
1318
1319 @item That piece of text is typeset with a font, unlike slurs or beams.
1320 @item Horizontally, the center of the symbol should be aligned to the
1321 center of the notehead
1322 @item Vertically, the symbol is placed next to the note and the staff.
1323
1324 @item The
1325  vertical position is also coordinated with other super and subscript
1326 symbols
1327 @end itemize
1328
1329 Each of these aspects is captured in a so-called @emph{interface},
1330 which are listed on the @internalsref{Fingering} page at the bottom
1331
1332 @quotation
1333 This object supports the following interfaces:
1334 @internalsref{item-interface},
1335 @internalsref{self-alignment-interface},
1336 @internalsref{side-position-interface}, @internalsref{text-interface},
1337 @internalsref{text-script-interface}, @internalsref{font-interface},
1338 @internalsref{finger-interface}, and @internalsref{grob-interface}.
1339 @end quotation
1340
1341 Clicking any of the links will take you to the page of the respective
1342 object interface.  Each interface has a number of properties.  Some of
1343 them are not user-serviceable (``Internal properties''), but others
1344 are.
1345
1346 We have been talking of `the' @code{Fingering} object, but actually it
1347 does not amount to much. The initialization file
1348 @file{scm/define-grobs.scm} shows the soul of the `object',
1349
1350 @verbatim
1351    (Fingering
1352      . (
1353         (print-function . ,Text_item::print)
1354         (padding . 0.6)
1355         (staff-padding . 0.6)
1356         (self-alignment-X . 0)
1357         (self-alignment-Y . 0)
1358         (script-priority . 100)
1359         (font-encoding . number)
1360         (font-size . -5)
1361         (meta . ((interfaces . (finger-interface font-interface
1362                text-script-interface text-interface
1363                side-position-interface self-alignment-interface
1364                item-interface))))
1365   ))
1366 @end verbatim
1367
1368 as you can see, @code{Fingering} is nothing more than a bunch of
1369 variable settings, and the webpage is directly generated from this
1370 definition.
1371
1372 @node Determining the grob property
1373 @subsection Determining the grob property
1374
1375
1376 Recall that we wanted to change the position of the @b{2} in 
1377
1378 @lilypond[fragment,relative=2,verbatim]
1379 c-2
1380 \stemUp
1381 f
1382 @end lilypond
1383
1384 Since the @b{2} is vertically positioned next to its note, we have to
1385 meddle with the interface associated with this positioning. This is
1386 done using @code{side-position-interface}. The page for this interface 
1387 says
1388
1389 @quotation
1390 @code{side-position-interface}
1391
1392   Position a victim object (this one) next to other objects (the
1393   support).  The property @code{direction} signifies where to put the
1394   victim object relative to the support (left or right, up or down?)
1395 @end quotation
1396
1397 @cindex padding
1398 @noindent
1399 below this description, the variable @code{padding} is described as
1400 @quotation
1401 @table @code
1402 @item padding
1403  (dimension, in staff space)
1404
1405  add this much extra space between objects that are next to each
1406   other. 
1407 @end table
1408 @end quotation
1409
1410 By increasing the value of @code{padding}, we can move away the
1411 fingering.  The following command inserts 3 staff spaces of white
1412 between the note and the fingering:
1413 @example
1414 \once \override Fingering #'padding = #3
1415 @end example
1416
1417 Inserting this command before the Fingering object is created,
1418 i.e. before @code{c2}, yields the following result:
1419
1420 @lilypond[relative=2,fragment,verbatim]
1421 \once \override Fingering
1422     #'padding = #3
1423 c-2
1424 \stemUp
1425 f
1426 @end lilypond
1427
1428
1429 In this case, the context for this tweak is @context{Voice}, which
1430 does not have to be specified for @code{\override}.  This fact can
1431 also be deduced from the program reference, for the page for the
1432 @internalsref{Fingering_engraver} plug-in says
1433
1434 @quotation
1435   Fingering_engraver is part of contexts: @dots{} @b{@internalsref{Voice}}
1436 @end quotation
1437
1438 @node Difficult tweaks
1439 @subsection Difficult tweaks
1440
1441 There are two classes of difficult adjustments. First, when there are
1442 several of the same objects at one point, and you want to adjust only
1443 one. For example, if you want to change only one note head in a chord.
1444
1445 In this case, the @code{\applyoutput} function must be used.  The
1446 next example defines a Scheme function @code{set-position-font-size}
1447 that sets the @code{font-size} property, but only  
1448 on objects that have @internalsref{note-head-interface} and are at the
1449 right Y-position.
1450
1451 @lilypond[verbatim]
1452 #(define ((set-position-font-size pos size) grob origin current)
1453   (let*
1454       ((interfaces (ly:grob-property grob 'interfaces))
1455        (position (ly:grob-property grob 'staff-position)))
1456   (if (and
1457   
1458         ; is this a note head?
1459         (memq 'note-head-interface interfaces)
1460
1461         ; is the Y coordinate right?
1462         (= pos position))
1463
1464       ; then do it.
1465       (set! (ly:grob-property grob 'font-size) size))))
1466
1467 \relative {
1468     c
1469     \applyoutput #(set-position-font-size -2 4)
1470     <c e g>
1471 }
1472 @end lilypond
1473
1474 @noindent
1475 A similar technique can be used for accidentals. In that case, the
1476 function should check for @code{accidental-interface}.
1477
1478 Another difficult adjustment is the appearance of spanner objects,
1479 such as slur and tie. Initially, only one of these objects is created,
1480 and they can be adjust with the normal mechanism. However, in some
1481 cases the spanners cross line breaks. If this happens, these objects
1482 are cloned.  A separate object is created for every system that it is
1483 in. These are clones of the original object and inherit all
1484 properties, including @code{\override}s.
1485
1486 In other words, an @code{\override} always affects all pieces of a
1487 broken spanner. To change only one part of a spanner at a line break,
1488 it is necessary to hook into the formatting process. The
1489 @code{after-line-breaking-callback} property contains the Scheme procedure
1490 that is called after line breaks have been determined, and layout
1491 objects have been split over different systems.
1492
1493 In the following example, we define a procedure
1494 @code{my-callback}. This procedure
1495  
1496 @itemize @bullet
1497 @item
1498 determines if we have been split across line breaks
1499 @item
1500 if yes, retrieves all the split objects
1501 @item
1502 checks if we are the last of the split objects
1503 @item
1504 if yes, it sets @code{extra-offset}.
1505 @end itemize
1506
1507 This procedure is installed into @internalsref{Tie}, so the last part
1508 of broken tie is translated up.
1509
1510
1511 @lilypond[verbatim,raggedright]
1512 #(define (my-callback grob)
1513   (let* (
1514
1515       ; have we been split? 
1516       (orig (ly:grob-original grob))
1517
1518       ; if yes, get the split pieces (our siblings)
1519       (siblings (if (ly:grob? orig) (ly:spanner-broken-into orig) '() )))
1520
1521       
1522     (if (and (>= (length siblings) 2)
1523              (eq? (car (last-pair siblings)) grob))
1524         (ly:grob-set-property! grob 'extra-offset '(-2 . 5))
1525         )))
1526
1527 \relative c'' { 
1528     \override Tie  #'after-line-breaking-callback =
1529     #my-callback
1530     c1 ~ \break c2 ~ c
1531 }
1532 @end lilypond
1533
1534
1535 When applying this trick, the new @code{after-line-breaking-callback}
1536 should also call the old @code{after-line-breaking-callback}, if there
1537 is one. For example, if using this with @code{Slur},
1538 @code{Slur::after_line_breaking} should also be called.
1539
1540 @node Fonts
1541 @section Fonts
1542
1543 @menu
1544 * Selecting font sizes::        
1545 * Font selection::              
1546 @end menu
1547
1548
1549
1550 @node Selecting font sizes
1551 @subsection Selecting font sizes
1552
1553 The most common thing to change about the appearance of fonts is their
1554 size. The font size of any context can be easily changed by setting
1555 the @code{fontSize} property for that context.  Its value is a number:
1556 negative numbers make the font smaller, positive numbers larger. An
1557 example is given below:
1558 @c
1559 @lilypond[fragment,relative=1,verbatim]
1560   c4 c4 \set fontSize = #-3
1561   f4 g4
1562 @end lilypond
1563 This command will set @code{font-size} (see below) in all layout
1564 objects in the current context. It does not change the size of
1565 variable symbols, such as beams or slurs.
1566
1567 The font size is set by modifying the @code{font-size} property.  Its
1568 value is a number indicating the size relative to the standard size.
1569 Each step up is an increase of approximately 12% of the font size. Six
1570 steps is exactly a factor two. The Scheme function @code{magstep}
1571 converts a @code{font-size} number to a scaling factor.
1572
1573 LilyPond has fonts in different design sizes: the music fonts for
1574 smaller sizes are chubbier, while the text fonts are relatively wider.
1575 Font size changes are achieved by scaling the design size that is
1576 closest to the desired size.
1577
1578 The @code{font-size} mechanism does not work for fonts selected
1579 through @code{font-name}. These may be scaled with
1580 @code{font-magnification}.
1581
1582
1583 One of the uses of @code{fontSize} is to get smaller symbols for cue
1584 notes. An elaborate example of those is in
1585 @inputfileref{input/test,cue-notes.ly}.
1586
1587 @cindex cue notes
1588 @cindex @code{font-style}
1589
1590 @refcommands
1591
1592 The following commands set @code{fontSize} for the current voice:
1593
1594 @cindex @code{\tiny}
1595 @code{\tiny}, 
1596 @cindex @code{\small}
1597 @code{\small}, 
1598 @cindex @code{\normalsize}
1599 @code{\normalsize}.
1600
1601
1602
1603 @cindex magnification
1604 @cindex cue notes
1605
1606
1607 @node Font selection
1608 @subsection Font selection
1609
1610 Font selection for the standard fonts, @TeX{}'s Computer Modern fonts,
1611 can also be adjusted with a more fine-grained mechanism.  By setting
1612 the object properties described below, you can select a different font;
1613 all three mechanisms work for every object that supports
1614 @code{font-interface}:
1615
1616
1617 @itemize @bullet
1618 @item @code{font-encoding}
1619 is a symbol that sets layout of the glyphs. Choices include @code{ec}
1620 for @TeX{} EC font encoding, @code{fetaBraces} (for piano staff
1621 braces), @code{fetaMusic} (the standard music font, including ancient
1622 glyphs), @code{fetaDynamic} (for dynamic signs) and @code{fetaNumber}
1623 for the number font.
1624
1625
1626 @item @code{font-family}
1627  is a symbol indicating the general class of the typeface.  Supported are
1628 @code{roman} (Computer Modern), @code{sans}, and @code{typewriter}.
1629   
1630 @item @code{font-shape}
1631   is a symbol indicating the shape of the font, there are typically
1632 several font shapes available for each font family. Choices are
1633 @code{italic}, @code{caps}, and @code{upright}.
1634
1635 @item @code{font-series}
1636 is a  symbol indicating the series of the font. There are typically several
1637 font series for each font family and shape. Choices are @code{medium}
1638 and @code{bold}. 
1639
1640 @end itemize
1641
1642 Fonts selected in the way sketched above come from a predefined style
1643 sheet.
1644
1645  The font used for printing a object can be selected by setting
1646 @code{font-name}, e.g.
1647 @example
1648   \override Staff.TimeSignature
1649       #'font-name = #"cmr17"
1650 @end example
1651
1652 @noindent
1653 Any font can be used, as long as it is available to @TeX{}. Possible
1654 fonts include foreign fonts or fonts that do not belong to the
1655 Computer Modern font family.  The size of fonts selected in this way
1656 can be changed with the @code{font-magnification} property.  For
1657 example, @code{2.0} blows up all letters by a factor 2 in both
1658 directions.
1659
1660 @cindex font size
1661 @cindex font magnification
1662
1663
1664
1665 @seealso
1666
1667 Init files: @file{ly/declarations-init.ly} contains hints how new
1668 fonts may be added to LilyPond.
1669
1670 @refbugs
1671
1672 No style sheet is provided for other fonts besides the @TeX{}
1673 Computer Modern family.
1674
1675 @cindex font selection
1676 @cindex font magnification
1677 @cindex @code{font-interface}
1678
1679
1680 @node Text markup
1681 @section Text markup
1682 @cindex text markup
1683 @cindex markup text
1684
1685
1686 @cindex typeset text
1687
1688 LilyPond has an internal mechanism to typeset texts. You can access it
1689 with the keyword @code{\markup}. Within markup mode, you can enter texts
1690 similar to lyrics: simply enter them, surrounded by spaces:
1691 @cindex markup
1692
1693 @lilypond[verbatim,fragment,relative=1]
1694  c1^\markup { hello }
1695  c1_\markup { hi there }
1696  c1^\markup { hi \bold there, is \italic anyone home? }
1697 @end lilypond
1698
1699 @cindex font switching
1700
1701 The markup in the example demonstrates font switching commands.  The
1702 command @code{\bold} and @code{\italic} apply to the first following 
1703 word only; enclose a set of texts with braces to apply a command
1704 to more words:
1705 @example
1706   \markup @{ \bold @{ hi there @} @}
1707 @end example
1708
1709 @noindent
1710 For clarity, you can also do this for single arguments, e.g.
1711
1712 @verbatim
1713   \markup { is \italic { anyone } home }
1714 @end verbatim
1715
1716 @cindex font size, texts
1717
1718
1719 In markup mode you can compose expressions, similar to mathematical
1720 expressions, XML documents, and music expressions.  The braces group
1721 notes into horizontal lines. Other types of lists also exist: you can
1722 stack expressions grouped with @code{<} and @code{>} vertically with
1723 the command @code{\column}. Similarly, @code{\center-align} aligns
1724 texts by their center lines:
1725
1726 @lilypond[verbatim,fragment,relative=1]
1727  c1^\markup { \column < a bbbb c > }
1728  c1^\markup { \center-align < a bbbb c > }
1729  c1^\markup { \line < a b c > }
1730 @end lilypond
1731
1732
1733 Markups can be stored in variables, and these variables
1734 may be attached to notes, like
1735 @verbatim
1736 allegro = \markup { \bold \large { Allegro } }
1737  { a^\allegro b c d }
1738 @end verbatim
1739
1740
1741 Some objects have alignment procedures of their own, which cancel out
1742 any effects of alignments applied to their markup arguments as a
1743 whole.  For example, the @internalsref{RehearsalMark} is horizontally
1744 centered, so using @code{\mark \markup @{ \left-align .. @}} has no
1745 effect.
1746
1747 Similarly, for moving whole texts over notes with
1748 @code{\raise}, use the following trick:
1749 @example
1750   "" \raise #0.5 raised
1751 @end example
1752
1753 The text @code{raised} is now raised relative to the empty string
1754 @code{""} which is not visible.  Alternatively, complete objects can
1755 be moved with layout properties such as @code{padding} and
1756 @code{extra-offset}.
1757
1758
1759
1760
1761 @seealso
1762
1763 Init files:  @file{scm/new-markup.scm}.
1764
1765
1766 @refbugs
1767
1768 Text layout is ultimately done by @TeX{}, which does kerning of
1769 letters.  LilyPond does not account for kerning, so texts will be
1770 spaced slightly too wide.
1771
1772 Syntax errors for markup mode are confusing.
1773
1774 Markup texts cannot be used in the titling of the @code{\header}
1775 field. Titles are made by La@TeX{}, so La@TeX{} commands should be used
1776 for formatting.
1777
1778
1779
1780 @menu
1781 * Text encoding::               
1782 * Nested scores::               
1783 * Overview of text markup commands::  
1784 @end menu
1785
1786 @node Text encoding
1787 @subsection Text encoding
1788
1789 Texts can be entered in different encodings.  The encoding of the
1790 file can be set with @code{\encoding}.
1791
1792 @example
1793   \encoding "latin1"
1794 @end example
1795
1796 This command may be placed anywhere in the input file. The current
1797 encoding is passed as an extra argument to @code{\markup} commands,
1798 and is passed similarly to lyric syllables.
1799
1800 If no @code{\encoding} has been specified, then the encoding is taken
1801 from the @code{\paper} block (or @code{\bookpaper}, if @code{\paper}
1802 does not specify encoding). The variable @code{inputencoding} may be
1803 set to a string or symbol specifying  the encoding, e.g.
1804
1805 @verbatim
1806   \paper {
1807     inputencoding = "latin1"
1808   } 
1809 @end verbatim
1810
1811 Normal strings, are unaffected by @code{\encoding}. This means that
1812 the following will usually not produce ba@ss{}tuba in the title.
1813
1814 @verbatim
1815   \header {
1816     title = "Grazing cow"
1817     instrument = "Baßtuba"
1818   }
1819 @end verbatim
1820
1821 Rather, you should say
1822 @verbatim
1823     instrument = \markup { Baßtuba }
1824 @end verbatim
1825
1826 @noindent
1827 or set @code{inputencoding} in the @code{\bookpaper} block. 
1828
1829 There is a special encoding, called @code{TeX}. This encoding does not
1830 reencode text for the font used. Rather, it tries to guess the width
1831 of @TeX{} commands, such as @code{\"}. Strings encoded with @code{TeX}
1832 are passed to the output back-end verbatim.
1833
1834 @cindex encoding
1835 @cindex @code{\encoding}
1836 @cindex inputencoding
1837 @cindex @TeX{} commands in strings
1838
1839
1840 @node Nested scores
1841 @subsection Nested scores
1842
1843 It is possible to nest music inside markups, by adding a @code{\score}
1844 block to markup expression. Such a score must contain a @code{\paper}
1845 block.
1846
1847 @lilypond[verbatim,raggedright]
1848 \relative {
1849   c4  d^\markup {
1850     \score {
1851       \relative { c4 d e f }
1852       \paper { }
1853     }
1854   }
1855   e f
1856 }
1857 @end lilypond
1858  
1859
1860
1861 @node  Overview of text markup commands
1862 @subsection Overview of text markup commands
1863
1864 @include markup-commands.tely
1865
1866
1867 @node Global layout
1868 @section Global layout
1869
1870 The global layout determined by three factors: the page layout, the
1871 line breaks, and the spacing. These all influence each other. The
1872 choice of spacing determines how densely each system of music is set,
1873 which influences where line breaks are chosen, and thus
1874 ultimately how many pages a piece of music takes. This section
1875 explains how to tune the algorithm for spacing.
1876
1877 Globally spoken, this procedure happens in three steps: first,
1878 flexible distances (``springs'') are chosen, based on durations. All
1879 possible line breaking combination are tried, and the one with the
1880 best results --- a layout that has uniform density and requires as
1881 little stretching or cramping as possible --- is chosen.
1882
1883 After spacing and linebreaking, the systems are distributed across
1884 pages, taking into account the size of the page, and the size of the
1885 titles.
1886
1887
1888
1889 @menu
1890 * Setting global staff size::   
1891 * Vertical spacing::            
1892 * Horizontal spacing::          
1893 * Line breaking::               
1894 * Line length and line breaking::  
1895 * Multiple movements::          
1896 * Titling::                     
1897 * Page breaking::               
1898 * Paper size::                  
1899 * Page layout::                 
1900 @end menu
1901
1902
1903 @node Setting global staff size
1904 @subsection Setting global staff size
1905
1906 @cindex font size, setting
1907 @cindex staff size, setting
1908 @cindex @code{paper} file
1909
1910 The Feta font provides musical symbols at eight  different
1911 sizes. Each font is tuned for a different staff size: at a smaller size
1912 the font becomes heavier, to match the relatively heavier staff lines.
1913 The recommended font sizes are listed in the following table:
1914
1915 @multitable @columnfractions  .25 .25 .25 .25
1916
1917 @item @b{font name}
1918 @tab @b{staff height (pt)}
1919 @tab @b{staff height (mm)}
1920 @tab @b{use}
1921
1922 @item feta11
1923 @tab 11.22
1924 @tab 3.9 
1925 @tab pocket scores
1926
1927 @item feta13
1928 @tab 12.60
1929 @tab 4.4
1930 @tab
1931
1932 @item feta14
1933 @tab 14.14
1934 @tab 5.0
1935 @tab 
1936
1937 @item feta16
1938 @tab 15.87
1939 @tab 5.6
1940 @tab 
1941
1942 @item feta18
1943 @tab 17.82
1944 @tab 6.3
1945 @tab song books
1946
1947 @item feta20
1948 @tab 17.82
1949 @tab 7.0
1950 @tab standard parts 
1951
1952 @item feta23
1953 @tab 22.45 
1954 @tab 7.9
1955 @tab 
1956
1957 @item feta26
1958 @tab 25.2 
1959 @tab 8.9
1960 @tab
1961 @c modern rental material  ?
1962
1963 @end multitable
1964
1965 These fonts are available in any sizes. The context property
1966 @code{fontSize} and the layout property @code{staff-space} (in
1967 @internalsref{StaffSymbol}) can be used to tune size for individual
1968 staves. The size of individual staves are relative to the global size,
1969 which can be set   in the following manner:
1970
1971 @example
1972   #(set-global-staff-size 14)
1973 @end example
1974
1975 This sets the global default size to 14pt staff height, and scales all
1976 fonts accordingly.
1977
1978 @seealso
1979
1980 This manual: @ref{Selecting font sizes}.
1981
1982
1983
1984 @menu
1985 * Vertical spacing::            
1986 * Horizontal spacing::          
1987 * Line breaking::               
1988 * Page layout::                 
1989 @end menu
1990
1991 @node Vertical spacing
1992 @subsection Vertical spacing
1993
1994 @cindex vertical spacing
1995 @cindex distance between staves
1996 @cindex staff distance
1997 @cindex between staves, distance
1998 @cindex staves per page
1999 @cindex space between staves
2000
2001 The height of each system is determined automatically by LilyPond, to
2002 keep systems from bumping into each other, some minimum distances are
2003 set.  By changing these, you can put staves closer together, and thus
2004 put more  systems onto one page.
2005
2006 Normally staves are stacked vertically. To make
2007 staves maintain a distance, their vertical size is padded. This is
2008 done with the property @code{minimumVerticalExtent}. It takes a pair
2009 of numbers, so if you want to make it smaller from its, then you could
2010 set
2011 @example
2012   \set Staff.minimumVerticalExtent = #'(-4 . 4)
2013 @end example
2014 This sets the vertical size of the current staff to 4 staff spaces on
2015 either side of the center staff line.  The argument of
2016 @code{minimumVerticalExtent} is interpreted as an interval, where the
2017 center line is the 0, so the first number is generally negative.  The
2018 staff can be made larger at the bottom by setting it to @code{(-6
2019 . 4)}.
2020
2021 The piano staves are handled a little differently: to make cross-staff
2022 beaming work correctly, it is necessary that the distance between staves
2023 is fixed beforehand.  This is also done with a
2024 @internalsref{VerticalAlignment} object, created in
2025 @internalsref{PianoStaff}. In this object the distance between the
2026 staves is fixed by setting @code{forced-distance}. If you want to
2027 override this, use a @code{\context} block as follows:
2028 @example
2029   \paper @{
2030     \context @{
2031       \PianoStaff
2032       \override VerticalAlignment #'forced-distance = #9
2033     @}
2034     @dots{}
2035   @}
2036 @end example
2037 This would bring the staves together at a distance of 9 staff spaces,
2038 measured from the center line of each staff.
2039
2040 @seealso
2041
2042 Internals: Vertical alignment of staves is handled by the
2043 @internalsref{VerticalAlignment} object.
2044
2045
2046
2047
2048 @node Horizontal spacing
2049 @subsection Horizontal Spacing
2050
2051 The spacing engine translates differences in durations into
2052 stretchable distances (``springs'') of differing lengths. Longer
2053 durations get more space, shorter durations get less.  The shortest
2054 durations get a fixed amount of space (which is controlled by
2055 @code{shortest-duration-space} in the @internalsref{SpacingSpanner} object). 
2056 The longer the duration, the more space it gets: doubling a
2057 duration adds a fixed amount (this amount is controlled by
2058 @code{spacing-increment}) of space to the note.
2059
2060 For example, the following piece contains lots of half, quarter, and
2061 8th notes, the eighth note is followed by 1 note head width (NHW). 
2062 The quarter note is followed by 2 NHW, the half by 3 NHW, etc.
2063 @lilypond[fragment,verbatim,relative=1] c2 c4. c8 c4. c8 c4. c8 c8
2064 c8 c4 c4 c4
2065 @end lilypond
2066
2067 Normally, @code{spacing-increment} is set to 1.2, which is the
2068 width of a note head, and @code{shortest-duration-space} is set to
2069 2.0, meaning that the shortest note gets 2 NHW  of space. For normal
2070 notes, this space is always counted from the left edge of the symbol, so
2071 the shortest notes are generally followed by one NHW of space.
2072
2073 If one would follow the above procedure exactly, then adding a single
2074 32th note to a score that uses 8th and 16th notes, would widen up the
2075 entire score a lot. The shortest note is no longer a 16th, but a 32nd,
2076 thus adding 1 NHW to every note. To prevent this, the
2077 shortest duration for spacing is not the shortest note in the score,
2078 but the most commonly found shortest note.  Notes that are even
2079 shorter this are followed by a space that is proportional to their
2080 duration relative to the common shortest note.  So if we were to add
2081 only a few 16th notes to the example above, they would be followed by
2082 half a NHW:
2083
2084 @lilypond[fragment,verbatim,relative=2]
2085  c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4
2086 @end lilypond
2087
2088 The most common shortest duration is determined as follows: in every
2089 measure, the shortest duration is determined. The most common short
2090 duration, is taken as the basis for the spacing, with the stipulation
2091 that this shortest duration should always be equal to or shorter than
2092 1/8th note. The shortest duration is printed when you run lilypond
2093 with @code{--verbose}.  These durations may also be customized. If you
2094 set the @code{common-shortest-duration} in
2095 @internalsref{SpacingSpanner}, then this sets the base duration for
2096 spacing. The maximum duration for this base (normally 1/8th), is set
2097 through @code{base-shortest-duration}.
2098
2099 @cindex @code{common-shortest-duration}
2100 @cindex @code{base-shortest-duration}
2101 @cindex @code{stem-spacing-correction}
2102 @cindex @code{spacing}
2103
2104 In the Introduction it was explained that stem directions influence
2105 spacing. This is controlled with @code{stem-spacing-correction}
2106 property in @internalsref{NoteSpacing}, which are generated for every
2107 @internalsref{Voice} context. The @code{StaffSpacing} object
2108 (generated at @internalsref{Staff} context) contains the same property
2109 for controlling the stem/bar line spacing. The following example
2110 shows these corrections, once with default settings, and once with
2111 exaggerated corrections:
2112
2113 @lilypond[raggedright]
2114 {
2115       c'4 e''4 e'4 b'4 |
2116       b'4 e''4 b'4 e''4|
2117       \override Staff.NoteSpacing #'stem-spacing-correction = #1.5
2118       \override Staff.StaffSpacing #'stem-spacing-correction = #1.5
2119       c'4 e''4 e'4 b'4 |
2120       b'4 e''4 b'4 e''4|      
2121 }
2122 @end lilypond
2123
2124 @cindex SpacingSpanner, overriding properties
2125
2126 Properties of the  @internalsref{SpacingSpanner} must be overridden
2127 from the @code{\paper} block, since the @internalsref{SpacingSpanner} is
2128 created before any property commands are interpreted.
2129 @example
2130 \paper @{ \context  @{
2131   \Score
2132   \override SpacingSpanner #'spacing-increment = #3.0
2133 @} @}
2134 @end example
2135
2136
2137 @seealso
2138
2139 Internals: @internalsref{SpacingSpanner}, @internalsref{NoteSpacing},
2140 @internalsref{StaffSpacing}, @internalsref{SeparationItem}, and
2141 @internalsref{SeparatingGroupSpanner}.
2142
2143 @refbugs
2144
2145 Spacing is determined on a score wide basis. If you have a score that
2146 changes its character (measured in durations) halfway during the
2147 score, the part containing the longer durations will be spaced too
2148 widely.
2149
2150 There is no convenient mechanism to manually override spacing.  The
2151 following work-around may be used to insert extra space into a score.
2152 @example
2153  \once \override Score.SeparationItem #'padding = #1
2154 @end example
2155
2156 No work-around exists for decreasing the amount of space.
2157
2158
2159 @node Line breaking
2160 @subsection Line breaking
2161
2162 @cindex line breaks
2163 @cindex breaking lines
2164
2165 Line breaks are normally computed automatically. They are chosen such
2166 that lines look neither cramped nor loose, and that consecutive lines
2167 have similar density.
2168
2169 Occasionally you might want to override the automatic breaks; you can
2170 do this by  specifying @code{\break}. This will force a line break at
2171 this point.  Line breaks can only occur at places where there are bar
2172 lines.  If you want to have a line break where there is no bar line,
2173 you can force an invisible bar line by entering @code{\bar
2174 ""}. Similarly, @code{\noBreak} forbids a line break at a 
2175 point.
2176
2177
2178 @cindex regular line breaks
2179 @cindex four bar music. 
2180
2181 For line breaks at regular intervals  use @code{\break} separated by
2182 skips and repeated with @code{\repeat}:
2183 @example
2184 <<  \repeat unfold 7 @{
2185          s1 \noBreak s1 \noBreak
2186          s1 \noBreak s1 \break  @}
2187    @emph{the real music}
2188 >> 
2189 @end  example
2190
2191 @noindent
2192 This makes the following 28 measures (assuming 4/4 time) be broken every
2193 4 measures, and only there.
2194
2195 @refcommands
2196
2197 @code{\break}, and @code{\noBreak}.
2198 @cindex @code{\break}
2199 @cindex @code{\noBreak}
2200
2201 @seealso
2202
2203 Internals: @internalsref{BreakEvent}.
2204
2205 @node Line length and line breaking
2206 @subsection Line length and line breaking
2207
2208 @cindex page breaks
2209 @cindex breaking pages
2210
2211 @cindex @code{indent}
2212 @cindex @code{linewidth}
2213
2214 The most basic settings influencing the spacing are @code{indent} and
2215 @code{linewidth}. They are set in the @code{\paper} block. They
2216 control the indentation of the first line of music, and the lengths of
2217 the lines.
2218
2219 If  @code{raggedright} is set to true in the @code{\paper}
2220 block, then the lines are justified at their natural length. This
2221 useful for short fragments, and for checking how tight the natural
2222 spacing is.
2223
2224 @cindex page layout
2225 @cindex vertical spacing
2226
2227 The option @code{raggedlast} is similar to @code{raggedright}, but
2228 only affects the last line of the piece. No restrictions are put on
2229 that line. The result is similar to formatting paragraphs. In a
2230 paragraph, the last line simply takes its natural length.
2231
2232
2233 @node Multiple movements
2234 @subsection Multiple movements
2235
2236 @cindex bibliographic information
2237 @cindex titles
2238 @cindex composer
2239 @cindex Engraved by LilyPond
2240
2241 A document may contains multiple pieces of music. Examples of these
2242 are an etude book, or an orchestral part with multiple movements.
2243 Each movement is entered with a @code{\score} block,
2244
2245 @example
2246   \score @{
2247      @var{..music..}
2248   @}
2249 @end example
2250
2251 The movements are combined together to  
2252 @code{\book} block is used to group the individual movements.
2253
2254 @example
2255 \book @{
2256   \score @{
2257      @var{..}
2258   @}
2259   \score @{
2260      @var{..}
2261   @}
2262 @}
2263 @end example
2264
2265
2266 The header for each piece of music can be put inside the @code{\score}
2267 block.  The @code{piece} name from the header will be printed before
2268 each movement.  The title for the entire book can be put inside the
2269 @code{\book}, but if it is not present, the @code{\header} which is at
2270 the top of the file is inserted.
2271
2272 @cindex Engraved by LilyPond
2273 @cindex signature line
2274
2275 @example 
2276 \book @{
2277   \header @{
2278     title = "Eight miniatures" 
2279     composer = "Igor Stravinsky"
2280   @}
2281   \score @{
2282     @dots{}
2283     \header @{ piece = "Romanze" @}
2284   @}
2285   \score @{
2286     @dots{}
2287     \header @{ piece = "Menuetto" @}
2288   @}
2289 @}
2290 @end example
2291
2292 @node Titling
2293 @subsection Titling
2294
2295 Titles are created for each @code{\score} block, and over a
2296 @code{\book}.
2297
2298 The contents of the titles are taken from the @code{\header} blocks.
2299 The header block for a book supports the following 
2300 @table @code
2301 @item title
2302     The title of the music. Centered on top of the first page.
2303 @item subtitle
2304     Subtitle, centered below the title.
2305 @item poet
2306     Name of the poet, left flushed below the subtitle.
2307 @item composer
2308     Name of the composer, right flushed below the subtitle.
2309 @item meter
2310     Meter string, left flushed below the poet.
2311 @item opus
2312     Name of the opus, right flushed below the composer.
2313 @item arranger
2314     Name of the arranger, right flushed below the opus.
2315 @item instrument
2316     Name of the instrument, centered below the arranger.
2317 @item dedication            
2318     To whom the piece is dedicated.
2319 @item piece
2320     Name of the piece, left flushed below the instrument.
2321 @end table
2322
2323 This is a demonstration of the fields available, 
2324
2325 @lilypond[verbatim]
2326 \book {
2327   \header {
2328     title = "Title"
2329     subtitle = "(and (the) subtitle)"
2330     subsubtitle = "Sub sub title"
2331     poet = "Poet"
2332     composer = "Composer"
2333     texttranslator = "Text Translator"
2334     meter = "Meter"
2335     arranger = "Arranger"
2336     instrument = "Instrument"
2337     piece = "Piece"
2338   }
2339
2340   \score {
2341     \header {
2342       piece = "piece1"
2343       opus = "opus1" 
2344     }
2345     { c'1 }
2346   }
2347   \score {
2348     \header {
2349       piece = "piece2"
2350       opus = "opus2" 
2351     }
2352     { c'1 }
2353   }
2354 }
2355 @end lilypond
2356
2357 Different fonts may be selected for each element, by using a
2358 @code{\markup}, e.g.
2359
2360 @verbatim
2361   \header {
2362     title = \markup { \italic { The italic title } }
2363   }
2364 @end verbatim
2365
2366 A more advanced option is to change the Scheme functions
2367 @code{make-book-title} and @code{make-score-title} functions, defined
2368 in the @code{\bookpaper} of the @code{\book} block. These functions
2369 create a block of titling, given the information in the
2370 @code{\header}. The init file @file{ly/titling.scm} shows how the
2371 default format is created, and it may be used as a template for
2372 different styles.
2373
2374  
2375 @cindex \bookpaper
2376 @cindex header
2377 @cindex footer
2378 @cindex page layout
2379 @cindex titles
2380
2381
2382
2383
2384 @node Page breaking
2385 @subsection Page breaking
2386
2387 The default page breaking may be overriden by inserting
2388 @code{\pageBreak} or @code{\noPageBreak} commands. These commands are
2389 analogous to @code{\break} and @code{\noBreak}. They should be
2390 inserted with a bar line. These commands force and forbid a page-break
2391 from happening. 
2392
2393 Page breaks are computed by the @code{page-breaking} function in the
2394 @code{\bookpaper} block. 
2395
2396 @refcommands
2397
2398 @cindex @code{\pageBreak}
2399 @code{\pageBreak}
2400 @cindex  @code{\noPageBreak} 
2401 @code{\noPageBreak} 
2402
2403 @node Paper size
2404 @subsection Paper size
2405
2406 @cindex paper size
2407 @cindex page size
2408 @cindex @code{papersize}
2409
2410 To change the paper size, there are two commands,
2411 @example
2412         #(set-default-paper-size "a4")
2413         \paper@{
2414            #(set-paper-size "a4")
2415         @}
2416 @end example
2417 The second one sets the size of the @code{\paper} block that it is in.
2418
2419
2420 @node Page layout
2421 @subsection Page layout
2422
2423 @cindex page layout
2424 @cindex margins
2425 @cindex header, page
2426 @cindex footer, page
2427
2428 LilyPond will do page layout, setting margins and adding headers and
2429 footers to each page.
2430
2431 The default layout responds to the following settings in the
2432 @code{\bookpaper} block
2433 @cindex \bookpaper
2434
2435 @table @code
2436 @item hsize
2437  The width of the page
2438 @item vsize
2439  The height of the page
2440 @item topmargin
2441  Margin between header and top of the page
2442 @item bottommargin
2443  Margin between footer and bottom of the page
2444 @item leftmargin
2445  Margin between the left side of the page and the beginning  of the music.
2446 @item linewidth
2447  The length of the paper line.
2448 @item headsep
2449  Distance between top-most music system and the page header
2450 @item footsep
2451  Distance between bottom-most music system and the page footer
2452 @item raggedbottom
2453  If set to true, systems will not be spread across the page.  
2454 @item raggedlastbottom
2455  If set to true, systems will not be spread to fill the last page.
2456 @end table
2457
2458 @example
2459         \bookpaper@{
2460            hsize = 2\cm
2461            topmargin = 3\cm
2462            bottommargin = 3\cm
2463            raggedlastbottom = ##t
2464         @}
2465 @end example
2466
2467 You can also define these values in scheme. In that case @code{mm},
2468 @code{in}, @code{pt} and @code{cm} are variables defined in
2469 @file{book-paper-defaults.ly} with values in millimeters. That's why the
2470 value has to be multiplied in the example above.
2471
2472 @example
2473         \bookpaper@{
2474         #(define bottommargin (* 2 cm)) 
2475         @}
2476 @end example
2477
2478
2479 @refbugs
2480
2481 The option rightmargin is defined but doesn't set the right margin
2482 yet. The value for the right margin has to be defined adjusting the
2483 values of the leftmargin and linewidth.
2484
2485 The default page header puts the page number and the @code{instrument}
2486 field from the @code{\header} block on a line.
2487
2488
2489
2490
2491 @cindex copyright
2492 @cindex tagline
2493
2494 The default footer is empty, except for the first page, where it the
2495 @code{copyright} field from @code{\header} is inserted, and the last
2496 page, where @code{tagline} from @code{\header} is added. The default
2497 tagline is ``Engraved by LilyPond (@var{version})''.@footnote{Nicely
2498 printed parts are good PR for us, so please leave the tagline if you
2499 can.}
2500
2501 The header and footer are created by the functions @code{make-footer}
2502 and @code{make-header}, defined in @code{\bookpaper}. The default
2503 implementations are in @file{scm/page-layout.scm}.
2504
2505 The following settings influence the header and footer layout.
2506
2507 @table @code
2508 @item printpagenumber
2509   this boolean controls whether a pagenumber is printed. 
2510 @end table
2511
2512
2513
2514 The page layout itself is done by two functions:
2515 @code{page-music-height} and @code{page-make-stencil}. The former
2516 tells the line-breaking algorithm how much space can be spent on a
2517 page, the latter creates the actual page given the system to put on it. 
2518
2519
2520 @seealso
2521
2522 Examples: @inputfileref{input/test/,page-breaks.ly}
2523
2524
2525