]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/user/tweaks.itely
Merge branch 'master' of git://git.sv.gnu.org/lilypond
[lilypond.git] / Documentation / user / tweaks.itely
1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond-learning.tely
3 @ignore
4     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
5
6     When revising a translation, copy the HEAD committish of the
7     version that you are working on.  See TRANSLATION for details.
8 @end ignore
9
10 @node Tweaking output
11 @chapter Tweaking output
12
13 This chapter discusses how to modify output.  LilyPond is extremely
14 configurable; virtually every fragment of output may be changed.
15
16 FIXME: explain what/why.  maybe in other sections.
17
18
19 @menu
20 * Tweaking basics::             
21 * The Internals Reference manual::  
22 * Common tweaks::               
23 * TODO other name::             
24 @end menu
25
26 @node Tweaking basics
27 @section Tweaking basics
28
29 NB: This section is still under development and may change
30
31 @q{Tweaking} is a LilyPond term for the various methods available
32 to the user for modifying the actions taken during interpretation
33 of the input file and modifying the appearance of the printed 
34 output.  Some tweaks are very easy to use; others are more 
35 complex.  But taken together the methods available for tweaking 
36 permit almost any desired appearance of the printed music to be achieved.
37
38 In this section we cover the basic concepts required to understand
39 tweaking.  Later we give a variety of potted commands which can
40 simply be copied to obtain the same effect in your own scores, and
41 at the same time we show how these commands may be constructed so 
42 that you may learn how to develop your own tweaks.
43
44 Before starting on this Chapter you may wish to review the section
45 @ref{Contexts and engravers}, as Contexts, Engravers and the 
46 Properties contained within them are fundamental to understanding
47 and constructing Tweaks.
48
49 @menu
50 * Objects and grobs and spanners and interfaces TODOname::  
51 * Naming conventions of objects and properties::  
52 * Tweaking methods::            
53 @end menu
54
55 @node Objects and grobs and spanners and interfaces TODOname
56 @subsection Objects and grobs and spanners and interfaces TODOname
57
58 cindex Objects
59 cindex Grobs
60 cindex Spanners
61 cindex Interfaces
62
63 Tweaking involves modifying the internal operation and structures
64 of the LilyPond program, so we must first introduce some terms
65 which are used to describe those internal operations and 
66 structures.
67
68 The term @q{Object} is a generic term used to refer to the
69 multitude of internal structures built by LilyPond during the
70 processing of an input file.  So when a command like @code{\new
71 Staff} is encountered a new object of type @code{Staff} is
72 constructed.  That @code{Staff} object then holds all the
73 properties associated with that particular staff, for example, its
74 name and its key signature, together with details of the engravers
75 which have been assigned to operate within that staff's context.
76 Similarly, there are @code{Voice} objects, @code{Score} objects,
77 @code{Lyric} objects, and objects to represent barlines,
78 noteheads, ties, dynamics, etc, each with their own set of
79 properties.
80
81 Some types of object are given special names.  Objects which
82 represent items of notation on the printed output such as
83 noteheads, stems, slurs, ties, fingering, clefs, etc are called
84 @q{Layout objects}, often known as @q{Graphical Objects}, or
85 @q{Grobs} for short.  These are still objects in the generic sense
86 above, and so they too all have properties associated with them,
87 such as their position, size, color, etc.
88
89 Some layout objects are still more specialised.  Phrasing slurs,
90 crescendo hairpins, ottavo marks, and many other grobs are not
91 localised in a single place -- they have a starting point, an
92 ending point, and maybe other properties concerned with their
93 shape.  Objects with an extended shape like these are called
94 @q{Spanners}.
95
96 It remains to explain what @q{Interfaces} are.  Many different
97 types of object often require to be processed in the same way.
98 For example, all grobs have a color, a size, a position, etc,
99 and all these properties are processed in the same way during
100 LilyPond's
101 interpretation of the input file.  To simplify these internal
102 operations these common actions and properties are grouped 
103 together in an object called a @code{grob-interface}.  Many
104 other groupings into interfaces are made.  In total there are
105 over 100 such interfaces.  We shall see later why this is of
106 interest and use to the user.
107
108 These, then, are the main terms relating to objects which we 
109 shall use in this chapter.
110
111 @node Naming conventions of objects and properties
112 @subsection Naming conventions of objects and properties
113
114 We met some object naming conventions previously, in 
115 @ref{Contexts and engravers}.  Here for reference is a list
116 of the most common object types together with the conventions
117 for naming them and a couple of examples of some real names.
118
119 @multitable @columnfractions .33 .33 .33
120 @headitem Object type           
121   @tab Naming convention
122   @tab Example
123 @item Contexts, Layout Objects     
124   @tab Aaaa or AaaaAaaaAaaa
125   @tab Staff, GrandStaff, 
126 @item Engravers
127   @tab Aaaa_aaa_engraver
128   @tab Clef_engraver, Note_heads_engraver
129 @item Interfaces
130   @tab aaa-aaa-interface
131   @tab grob-interface, break-aligned-interface 
132 @item Context Properties
133   @tab aaa or aaaAaaaAaaa
134   @tab alignAboveContext, skipBars
135 @item Layout Object Properties
136   @tab aaa or aaa-aaa-aaa
137   @tab direction, beam-thickness
138 @end multitable
139
140 As we shall see shortly, the properties of different types of 
141 object are modified by different commands, so it is useful to
142 be able to recognise the type of object from the names of its
143 properties.
144
145
146 @node Tweaking methods
147 @subsection Tweaking methods
148
149 We have already met the commands @code{\set} and @code{\with},
150 used to change the properties of @strong{contexts} and to remove
151 and add
152 engravers, in @ref{Modifying context properties} and @ref{Adding
153 and removing engravers}.  We now must meet one more command.
154
155 The command to change the properties of @strong{layout objects} is
156 @code{\override}.  Because this command has to modify
157 internal properties deep within LilyPond its syntax is not
158 as simple as the commands you have met so far.  It needs to
159 know precisely which property of which object in which context
160 has to be modified, and what its new value is to be.  Let's see
161 how this is done.
162
163 The general syntax of this command is:
164
165 @example
166 \override @emph{context}.@emph{layout_object}
167   #'@emph{layout_property} = #@emph{value}
168 @end example
169
170 @noindent
171 This will set the @emph{layout_property} of the specified 
172 @emph{layout_object}, which is a member of the @emph{context}
173 context, to the value @emph{value}.
174
175 For now, don't worry about the @code{#'}, which must precede the
176 layout property, and the @code{#}, which must precede the value.
177 These must always be present in exactly this form.  This is the
178 most common command used in tweaking, and most of the rest of
179 this chapter will be directed to presenting examples of how it is
180 used.
181
182 There is another form of the override command, 
183 @code{\overrideProperty}, which is occasionally required.  
184 We mention it here for completeness, but for details see 
185 @ruser{Difficult tweaks}.
186
187 The final tweaking command which is available is @code{\tweak}.
188 It is not really a new command but a shorthand for an 
189 @code{\override} command which may be used in a few special 
190 circumstances.  Again, we shall not discuss or 
191 use it here.  You may find the details in @ruser{Objects 
192 connected to the input}.
193
194 @node The Internals Reference manual
195 @section The Internals Reference manual
196
197 @cindex Internals Reference
198
199 Suppose you have a slur in a score which, to your mind,
200 appears too thin and you'd like to draw it a little thicker.
201 How do you go about doing this?  You know from the statements
202 earlier about the flexibility of LilyPond that such a thing
203 should be possible, and you would probably guess that an
204 @code{\override} command would be needed.  But is there a
205 thickness property for a slur, and if there is, how might it 
206 be modified?  This is where the Internals Reference manual
207 comes in.  It contains all the information you might need to
208 construct this and all other @code{\override} commands.
209
210 Before we look at the Internals Reference a word of warning.
211 This is a @strong{reference} document, which means there is
212 little or no explanation contained within it: its purpose is
213 to present information precisely and concisely.  This
214 might mean it looks daunting at first sight.  Don't worry!
215 The guidance and explanation presented here will enable you
216 to extract the information from the Internals Reference for
217 yourself with just a little practice.
218
219 Let's use a concrete example.    
220
221 ... to be continued
222  
223
224 @c Old stuff follows  -td
225
226 @node Common tweaks
227 @section Common tweaks
228
229 blah blah
230
231 @menu
232 * Moving objects::              
233 * Fixing overlapping notation::  
234 * Other common tweaks::         
235 * Fitting music onto fewer pages::  
236 @end menu
237
238 @node Moving objects
239 @subsection Moving objects
240
241 This may come as a surprise, but LilyPond is not perfect.  Some notation
242 elements can overlap.  This is unfortunate, but (in most cases) is easily
243 solved.
244
245 TODO: with the new spacing features in 2.12, these specific examples are no
246 longer relevant.  However, they still demonstrate powerful features
247 of lilypond, so they remain until somebody creates some better examples.
248
249 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
250   % temporary code to break this example:
251   \override TextScript #'outside-staff-priority = ##f
252 e4^\markup{ \italic ritenuto } g b e
253 @end lilypond
254
255 @cindex padding
256
257 The easiest solution is to increase the distance between the object
258 (in this case text, but it could easily be fingerings or dynamics
259 instead) and the note.  In LilyPond, this is called the
260 @code{padding} property; it is measured in staff spaces.  For most
261 objects, this value is around 1.0 or less (it varies with each
262 object).  We want to increase it, so let's try 1.5
263
264 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
265   % temporary code to break this example:
266   \override TextScript #'outside-staff-priority = ##f
267 \once \override TextScript #'padding = #1.5
268 e4^\markup{ \italic ritenuto } g b e
269 @end lilypond
270
271 That looks better, but it isn't quite big enough.  After experimenting
272 with a few values, we think 2.3 is the best number in this case.  However,
273 this number is merely the result of experimentation and my personal
274 taste in notation.  Try the above example with 2.3... but also try higher
275 (and lower) numbers.  Which do you think looks the best?
276
277 The @code{staff-padding} property is closely related.  @code{padding}
278 controls the minimum amount of space between an object and the nearest
279 other object (generally the note or the staff lines);
280 @code{staff-padding} controls the minimum amount of space between an
281 object and the staff.  This is a subtle difference, but you can see
282 the behavior here.
283
284 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
285   % temporary code to break this example:
286   \override TextScript #'outside-staff-priority = ##f
287 c4^"piu mosso" b a b
288 \once \override TextScript #'padding = #4.6
289 c4^"piu mosso" d e f
290 \once \override TextScript #'staff-padding = #4.6
291 c4^"piu mosso" fis a g
292 \break
293 c'4^"piu mosso" b a b
294 \once \override TextScript #'padding = #4.6
295 c4^"piu mosso" d e f
296 \once \override TextScript #'staff-padding = #4.6
297 c4^"piu mosso" fis a g
298 @end lilypond
299
300 @cindex extra-offset
301
302 Another solution gives us complete control over placing the object -- we
303 can move it horizontally or vertically.  This is done with the
304 @code{extra-offset} property.  It is slightly more complicated and can
305 cause other problems.  When we move objects with @code{extra-offset},
306 the movement is done after LilyPond has placed all other objects.  This
307 means
308 that the result can overlap with other objects.
309
310 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
311   % temporary code to break this example:
312   \override TextScript #'outside-staff-priority = ##f
313 \once \override TextScript #'extra-offset = #'( 1.0 . -1.0 )
314 e4^\markup{ \italic ritenuto } g b e
315 @end lilypond
316
317 With @code{extra-offset}, the first number controls the horizontal
318 movement (left is negative); the second number controls the vertical
319 movement (up is positive).  After a bit of experimenting, we decided
320 that these values look good
321
322 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
323   % temporary code to break this example:
324   \override TextScript #'outside-staff-priority = ##f
325 \once \override TextScript #'extra-offset = #'( -1.6 . 1.0 )
326 e4^\markup{ \italic ritenuto } g b e
327 @end lilypond
328
329 @noindent
330 Again, these numbers are simply the result of a few experiments and
331 looking at the output.  You might prefer the text to be slightly higher,
332 or to the left, or whatever.  Try it and look at the result!
333
334 One final warning: in this section, we used
335
336 @example
337 \once \override TextScript @dots{}
338 @end example
339
340 This tweaks the display of text for the next note.  If the note has
341 no text, this tweak does nothing (and does @strong{not} wait until
342 the next bit of text).  To change the behavior of everything after
343 the command, omit the @code{\once}.  To stop this tweak, use a
344 @code{\revert}.  This is explained in depth in
345 @ruser{The \override command}.
346
347 @lilypond[quote,fragment,ragged-right,verbatim,relative=3]
348   % temporary code to break this example:
349   \override TextScript #'outside-staff-priority = ##f
350 c4^"piu mosso" b
351 \once \override TextScript #'padding = #4.6
352   a4 b
353 c4^"piu mosso" d e f
354 \once \override TextScript #'padding = #4.6
355 c4^"piu mosso" d e f
356 c4^"piu mosso" d e f
357 \break
358 \override TextScript #'padding = #4.6
359 c4^"piu mosso" d e f
360 c4^"piu mosso" d e f
361 \revert TextScript #'padding
362 c4^"piu mosso" d e f
363 @end lilypond
364
365 @seealso
366
367 This manual: @ruser{The \override command}, @ref{Common tweaks}.
368
369
370 @node Fixing overlapping notation
371 @subsection Fixing overlapping notation
372
373 In @ref{Moving objects}, we saw how to move a @code{TextScript}
374 object.  The same mechanism can be used to move other types of
375 objects; simply replace @code{TextScript} with the name of
376 another object.
377
378 To find the object name, look at the @q{@strong{see also}} at
379 bottom of the relevant documentation page.  For example, at
380 the bottom of @ruser{Dynamics}, we see
381
382 @quotation
383 @seealso
384
385 Internals Reference: @internalsref{DynamicText}, @internalsref{Hairpin}.
386 Vertical positioning of these symbols is handled by
387 @internalsref{DynamicLineSpanner}.
388 @end quotation
389
390 @noindent
391 So to move dynamics around vertically, we use
392
393 @example
394 \override DynamicLineSpanner #'padding = #2.0
395 @end example
396
397 We cannot list every object, but here is a list of the most
398 common objects.
399
400 @multitable @columnfractions .33 .66
401 @headitem Object type           @tab Object name
402 @item Dynamics (vertically)     @tab @code{DynamicLineSpanner}
403 @item Dynamics (horizontally)   @tab @code{DynamicText}
404 @item Ties                      @tab @code{Tie}
405 @item Slurs                     @tab @code{Slur}
406 @item Articulations             @tab @code{Script}
407 @item Fingerings                @tab @code{Fingering}
408 @item Text e.g. @code{^"text"}  @tab @code{TextScript}
409 @item Rehearsal / Text marks    @tab @code{RehearsalMark}
410 @end multitable
411
412
413 @node Other common tweaks
414 @subsection Other common tweaks
415
416 Some overrides are so common that predefined commands are provided as
417 short-cuts, such as @code{\slurUp} and @code{\stemDown}.  These
418 commands are described in the Notation Reference under the appropriate
419 sections.
420
421 The complete list of modifications available for each type of
422 object (like slurs or beams) are documented in the Program
423 Reference.  However, many layout objects share properties which can be
424 used to apply generic tweaks.
425
426 @itemize
427
428 @cindex padding
429
430 @item
431 The @code{padding} property can be set to increase
432 (or decrease) the distance between symbols that are printed
433 above or below notes.  This applies to all objects with
434 @code{side-position-interface}.
435
436 @lilypond[quote,fragment,relative=1,verbatim]
437 c2\fermata
438 \override Script #'padding = #3
439 b2\fermata
440 @end lilypond
441
442 @lilypond[quote,fragment,relative=1,verbatim]
443 % This will not work, see below:
444 \override MetronomeMark #'padding = #3
445 \tempo 4=120
446 c1
447 % This works:
448 \override Score.MetronomeMark #'padding = #3
449 \tempo 4=80
450 d1
451 @end lilypond
452
453 Note in the second example how important it is to figure out what
454 context handles a certain object.  Since the @code{MetronomeMark} object
455 is handled in the @code{Score} context, property changes in the
456 @code{Voice} context will not be noticed.  For more details, see
457 @ruser{Constructing a tweak}.
458
459 @cindex extra-offset
460
461 @item
462 The @code{extra-offset} property moves objects around
463 in the output; it requires a pair of numbers.  The first number
464 controls horizontal movement; a positive number will
465 move the object to the right.  The second number controls vertical
466 movement; a positive number will move it higher.  The
467 @code{extra-offset} property is a low-level feature: the
468 formatting engine is completely oblivious to these offsets.
469
470 In the following example, the second fingering is moved a little to
471 the left, and 1.8 staff space downwards:
472
473 @lilypond[quote,fragment,relative=1,verbatim]
474 \stemUp
475 f-5
476 \once \override Fingering
477     #'extra-offset = #'(-0.3 . -1.8)
478 f-5
479 @end lilypond
480
481 @item
482 Setting the @code{transparent} property will cause an object to be printed
483 in @q{invisible ink}: the object is not printed, but all its other
484 behavior is retained.  The object still takes up space, it takes part in
485 collisions, and slurs, ties, and beams can be attached to it.
486
487 @cindex transparent objects
488 @cindex removing objects
489 @cindex hiding objects
490 @cindex invisible objects
491 The following example demonstrates how to connect different voices
492 using ties.  Normally, ties only connect two notes in the same
493 voice.  By introducing a tie in a different voice,
494
495 @lilypond[quote,fragment,relative=2]
496 << {
497   b8~ b8\noBeam
498 } \\ {
499   b[ g8]
500 } >>
501 @end lilypond
502
503 @noindent
504 and blanking the first up-stem in that voice, the tie appears to cross
505 voices:
506
507
508 @lilypond[quote,fragment,relative=2,verbatim]
509 << {
510   \once \override Stem #'transparent = ##t
511   b8~ b8\noBeam
512 } \\ {
513   b[ g8]
514 } >>
515 @end lilypond
516
517 To make sure that the just-blanked stem doesn't squeeze the tie too much,
518 we also lengthen the stem, by setting the @code{length} to
519 @code{8},
520
521 @lilypond[quote,fragment,relative=2,verbatim]
522 << {
523   \once \override Stem #'transparent = ##t
524   \once \override Stem #'length = #8
525   b8~ b8\noBeam
526 } \\ {
527   b[ g8]
528 } >>
529 @end lilypond
530
531 @end itemize
532
533 @cindex Tweaks, distances
534 @cindex Distances
535
536 Distances in LilyPond are measured in staff-spaces, while most
537 thickness properties are measured in line-thickness.  Some
538 properties are different; for example, the thickness of beams
539 are measured in staff-spaces.  For more information, see the
540 relevant portion of the program reference.
541
542
543 @node Fitting music onto fewer pages
544 @subsection Fitting music onto fewer pages
545
546 Sometimes you can end up with one or two staves on a second
547 (or third, or fourth...) page.  This is annoying, especially
548 if you look at previous pages and it looks like there is plenty
549 of room left on those.
550
551 When investigating layout issues, @code{annotate-spacing} is
552 an invaluable tool.  This command prints the values of various
553 layout spacing commands; see @ruser{Displaying spacing}, for more
554 details.  From the output of @code{annotate-spacing}, we can
555 see which margins we may wish to alter.
556
557 Other than margins, there are a few other options to save space:
558
559 @itemize
560 @item
561 You may tell LilyPond to place systems as close together as
562 possible (to fit as many systems as possible onto a page), but
563 then to space those systems out so that there is no blank
564 space at the bottom of the page.
565
566 @example
567 \paper @{
568   between-system-padding = #0.1
569   between-system-space = #0.1
570   ragged-last-bottom = ##f
571   ragged-bottom = ##f
572 @}
573 @end example
574
575 @item
576 You may force the number of systems (i.e., if LilyPond wants
577 to typeset some music with 11 systems, you could force it to
578 use 10).
579
580 @example
581 \paper @{
582   system-count = #10
583 @}
584 @end example
585
586 @item
587 Avoid (or reduce) objects which increase the vertical size of
588 a system.  For example, volta repeats (or alternate repeats)
589 require extra space.  If these repeats are spread over two
590 systems, they will take up more space than one system with
591 the volta repeats and another system without.
592
593 Another example is moving dynamics which @q{stick out} of
594 a system.
595
596 @lilypond[verbatim,quote,fragment]
597 \relative c' {
598   e4 c g\f c
599   \override DynamicLineSpanner #'padding = #-1.8
600   \override DynamicText #'extra-offset = #'( -2.1 . 0)
601   e4 c g\f c
602 }
603 @end lilypond
604
605 @item
606 Alter the horizontal spacing via @code{SpacingSpanner}.  See
607 @ruser{Changing horizontal spacing}, for more details.
608
609 @lilypond[verbatim,quote]
610 \score {
611   \relative c'' {
612     g4 e e2 | f4 d d2 | c4 d e f | g4 g g2 |
613     g4 e e2 | f4 d d2 | c4 e g g | c,1 |
614     d4 d d d | d4 e f2 | e4 e e e | e4 f g2 |
615     g4 e e2 | f4 d d2 | c4 e g g | c,1 |
616   }
617   \layout {
618     \context {
619       \Score
620       \override SpacingSpanner
621                 #'base-shortest-duration = #(ly:make-moment 1 4)
622     }
623   }
624 }
625 @end lilypond
626
627 @end itemize
628
629
630 @node TODO other name
631 @section TODO other name
632
633 @menu
634 * Predefined tweaks::           
635 * Advanced tweaks with Scheme::  
636 * Avoiding tweaks with slower processing::  
637 * The three methods of tweaking::  
638 @end menu
639
640 @node Predefined tweaks
641 @subsection Predefined tweaks
642
643 TODO: Some tweaks are really common, blah blah.
644
645 for example \slurUp, \fatText.
646
647 Show example, then explain where to find ly/propert-ly.
648
649
650 The Internals Reference documentation contains a lot of information
651 about LilyPond, but even more information can be gathered from
652 looking at the internal LilyPond files.
653
654 Some default settings (such as the definitions for
655 @code{\header@{@}}s) are stored as @code{.ly} files.  Other
656 settings (such as the definitions of markup commands) are
657 stored as @code{.scm} (Scheme) files.  Further explanation is
658 outside the scope of this manual; users should be warned that
659 a substantial amount of technical knowledge or time is required
660 to understand these files.
661
662 @itemize
663
664 @item Linux: @file{@var{installdir}/lilypond/usr/share/lilypond/current/}
665
666 @item OSX:
667 @file{@var{installdir}/LilyPond.app/Contents/Resources/share/lilypond/current/}.
668 To access this, either @code{cd} into this directory from the
669 Terminal, or control-click on the LilyPond application and select
670 @q{Show Package Contents}.
671
672 @item Windows: @file{@var{installdir}/LilyPond/usr/share/lilypond/current/}
673
674 @end itemize
675
676 The @file{ly/} and @file{scm/} directories will be of
677 particular interest.  Files such as @file{ly/property-init.ly} and
678 @file{ly/declarations-init.ly} define all the common tweaks.
679
680
681 @node Advanced tweaks with Scheme
682 @subsection Advanced tweaks with Scheme
683
684 We have seen how LilyPond output can be heavily modified using
685 commands like
686 @code{\override TextScript #'extra-offset = ( 1 . -1)}.  But
687 we have even more power if we use Scheme.  For a full explantion
688 of this, see the @ref{Scheme tutorial}, and
689 @ruser{Interfaces for programmers}.
690
691 We can use Scheme to simply @code{\override} commands,
692
693 @lilypond[quote,verbatim,ragged-right]
694 padText = #(define-music-function (parser location padding) (number?)
695 #{
696   \once \override TextScript #'padding = #$padding
697 #})
698
699 \relative c''' {
700   c4^"piu mosso" b a b
701   \padText #1.8
702   c4^"piu mosso" d e f
703   \padText #2.6
704   c4^"piu mosso" fis a g
705 }
706 @end lilypond
707
708 We can use it to create new commands,
709
710 @lilypond[quote,verbatim,ragged-right]
711 tempoMark = #(define-music-function (parser location padding marktext)
712                                     (number? string?)
713 #{
714   \once \override Score . RehearsalMark #'padding = $padding
715   \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
716   \mark \markup { \bold $marktext }
717 #})
718
719 \relative c'' {
720   c2 e
721   \tempoMark #3.0 #"Allegro"
722   g c
723 }
724 @end lilypond
725
726 Even music expressions can be passed in.
727
728 @lilypond[quote,verbatim,ragged-right]
729 pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)
730 #{
731   $x e8 a b $y b a e
732 #})
733
734 \relative c''{
735   \pattern c8 c8\f
736   \pattern {d16 dis} { ais16-> b\p }
737 }
738 @end lilypond
739
740
741 @node Avoiding tweaks with slower processing
742 @subsection Avoiding tweaks with slower processing
743
744 LilyPond can perform extra checks while it processes files.  These
745 commands will take extra time, but the result may require fewer
746 manual tweaks.
747
748 @example
749 %%  makes sure text scripts and lyrics are within the paper margins
750 \override Score.PaperColumn #'keep-inside-line = ##t 
751 \override Score.NonMusicalPaperColumn #'keep-inside-line = ##t
752 @end example
753
754 In some cases (see issue 246), this must be done before
755 @code{\override} commands can be processed.
756
757 @verbatim
758 \new Score \with {
759     \override PaperColumn #'keep-inside-line = ##t 
760     \override NonMusicalPaperColumn #'keep-inside-line = ##t
761   } {
762    ..
763 }
764 @end verbatim
765
766
767 @node The three methods of tweaking
768 @subsection The three methods of tweaking
769
770 FIXME write this.
771
772 @verbatim
773 \override
774 @end verbatim
775
776 @verbatim
777 \with {
778
779 }
780 @end verbatim
781
782 @verbatim
783 \layout{ \context
784
785 }}
786 @end verbatim
787
788
789
790 FIXME discuss \tweak
791
792
793
794 FIXME: Move the following words and example into Tweaks or
795 somewhere more suitable, leaving just a ref here. -td
796
797 Ways of correcting horizontal placings are described fully 
798 in the Notation Reference.  
799 We introduce just one here, the @code{force-hshift} property of 
800 @code{NoteColumn}.  The lower two notes of the first chord (i.e,
801 those in the third voice) should not be shifted away from the
802 note column of the higher two notes.  To correct this we set
803 @code{force-hshift} of these notes to zero.  
804 The lower note of the second chord is best placed just to the 
805 right of the higher notes.  We achieve this by setting
806 @code{force-hshift} of this note to 0.5, ie half a notehead's 
807 width to the right of the note column of the higher notes.
808
809 Here's the final result:
810     
811 @lilypond[quote,verbatim,fragment,ragged-right]
812 \new Staff \relative c'' {
813   \key aes \major
814   << 
815     { c2 aes4. bes8 } \\ 
816     { aes2 f4 fes   } \\ 
817     { \voiceFour
818       \once \override NoteColumn #'force-hshift = #0 <ees c>2
819       \once \override NoteColumn #'force-hshift = #0.5 des2 
820     }
821   >> |
822   <c ees aes c>1 |
823 }
824 @end lilypond
825
826
827
828
829 FIXME:
830 - There is a section in the manual on \set vs \override (3.3.7),
831 which is incomplete.  First it doesn't mention \overrideProperty,
832 nor does it mention properties which are not capitalized at all.
833 And it should explain that \override should be used to set
834 properties with hyphenated names, like auto-knee-gap.  (I had to
835 experiment to find out how to do this.)
836
837
838 FIXME: moved from fundamental, dumped here at random.
839
840 @lilypond[verbatim,quote,ragged-right]
841 \new Staff = "main" {
842   \relative g' {
843     r4 g8 g c4 c8 d |
844     e4
845     <<  % Start main and ossia in parallel
846       { r8 f c c }  % Main music
847       \new Staff \with {  % Start ossia staff
848         \remove "Clef_engraver"
849         \remove "Time_signature_engraver"
850         % Reduce size of notes and staff
851         fontSize = #-2
852         \override StaffSymbol #'staff-space = #(magstep -2)
853         alignAboveContext = "main"  % Place above main staff
854       }
855       { s8 f f c }  % Ossia music
856     >>  % End parallel music
857     r4 |
858   }
859 }
860 @end lilypond
861
862