]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/nl/notation/changing-defaults.itely
Doc: [nl] add tutorial.itely.
[lilypond.git] / Documentation / nl / notation / changing-defaults.itely
1 \input texinfo @c -*- coding: utf-8; mode: texinfo; documentlanguage: nl -*-
2 @c This file is part of notation.tely
3 @ignore
4     Translation of GIT committish: 1b3da70d81938d19a2b107382bbe25a267cf130b
5
6     When revising a translation, copy the HEAD committish of the
7     version that you are working on.  For details, see the Contributors'
8     Guide, node Updating translation committishes..
9 @end ignore
10
11
12 @c -*- coding: utf-8; mode: texinfo; -*-
13 @c \version "2.12.0"
14 @node Changing defaults
15 @chapter Changing defaults
16
17 @untranslated
18
19
20 @c index Internals Reference
21 @c leave the @uref as one long line.
22 @c ode{#}.@footnote{@rlearning{Scheme tutorial}, contains a short tutorial
23 @menu
24 * Interpretation contexts::
25 * Explaining the Internals Reference::
26 * Modifying properties::
27 * Useful concepts and properties::
28 * Advanced tweaks::
29 @end menu
30
31 @node Interpretation contexts
32 @section Interpretation contexts
33
34 @untranslated
35
36
37 @menu
38 * Contexts explained::
39 * Creating contexts::
40 * Keeping contexts alive::
41 * Modifying context plug-ins::
42 * Changing context default settings::
43 * Defining new contexts::
44 * Aligning contexts::
45 @end menu
46
47 @node Contexts explained
48 @subsection Contexts explained
49
50 @untranslated
51
52
53 @c TODO Rethink and rewrite
54 @c TODO Improve layout, order and consistency of wording -td
55 @c TODO Add introduction which explains contexts in generality  -td
56 @c TODO Describe propagation of property values -td
57 @menu
58 * Score - the master of all contexts::
59 * Top-level contexts - staff containers::
60 * Intermediate-level contexts - staves::
61 * Bottom-level contexts - voices::
62 @end menu
63
64 @node Score - the master of all contexts
65 @unnumberedsubsubsec Score - the master of all contexts
66
67 @untranslated
68
69
70 @c ode{\score @{@dots{}@}} or @code{\layout @{@dots{}@}} block is
71 @node Top-level contexts - staff containers
72 @unnumberedsubsubsec Top-level contexts - staff containers
73
74 @untranslated
75
76
77 @node Intermediate-level contexts - staves
78 @unnumberedsubsubsec Intermediate-level contexts - staves
79
80 @untranslated
81
82
83 @c ode{Voice} contexts.
84 @node Bottom-level contexts - voices
85 @unnumberedsubsubsec Bottom-level contexts - voices
86
87 @untranslated
88
89
90 @node Creating contexts
91 @subsection Creating contexts
92
93 @untranslated
94
95
96 @c TODO \new Score and \score
97 @c TODO more complete descriptions rather than learning style
98 @c index new contexts
99 @c index Context, creating
100 @c ode{Voice}).  This command creates a new context, and starts
101 @c ode{\new Staff}.
102 @c index creating contexts
103 @ref{Running a function on all layout objects}).  Without an explicit
104 @c ode{\context}, it is usually applied to @code{Voice}
105 @node Keeping contexts alive
106 @subsection Keeping contexts alive
107
108 @untranslated
109
110
111 @c index contexts, keeping alive
112 @c index contexts, lifetime
113 @c ode{\change} commands, associating lyrics with a voice with
114 @c ode{\lyricsto} commands, or when adding further musical events to
115 @c ode{Voice} contexts in a @code{Staff} context or in a
116 @c ode{<<...>>} construct will always persist to the end of the
117 @c ode{<<...>>} constructs.
118 @c index lyrics, aligning with sporadic melody
119 @node Modifying context plug-ins
120 @subsection Modifying context plug-ins
121
122 @untranslated
123
124
125 @c TODO Should this be Modifying engravers or Modifying contexts?
126 @c ode{Note_head_engraver} and the @code{Staff} context contains a
127 @c ode{Key_signature_engraver}.
128 @c ode{Clef_engraver} from a @code{Staff} context,
129 @c ode{Staff} context, we can have a score where each staff has its own
130 @c index polymetric scores
131 @c index Time signatures, multiple
132 @c ode{Bar_engraver} must normally be first, and
133 @node Changing context default settings
134 @subsection Changing context default settings
135
136 @untranslated
137
138
139 @c ode{Score}, @code{Staff} and @code{Voice} contexts may be specified
140 @c ode{Voice} contexts in a similar way.
141 @c ode{\Staff} settings.  If you wish to change the defaults for a
142 @c TODO: add \with in here.
143 @node Defining new contexts
144 @subsection Defining new contexts
145
146 @untranslated
147
148
149 @c ode{Voice} context from scratch.  It will be similar to
150 @c ode{Voice}, but only prints centered slash note heads.  It can be used
151 @c ode{\layout} block,
152 @node Aligning contexts
153 @subsection Aligning contexts
154
155 @untranslated
156
157
158 @c TODO Better example needed.  Ref LM, and expand on it.
159 @c index ossia
160 @c index nested contexts
161 @c index contexts, nested
162 @node Explaining the Internals Reference
163 @section Explaining the Internals Reference
164
165 @untranslated
166
167
168 @menu
169 * Navigating the program reference::
170 * Layout interfaces::
171 * Determining the grob property::
172 * Naming conventions::
173 @end menu
174
175 @node Navigating the program reference
176 @subsection Navigating the program reference
177
178 @untranslated
179
180
181 @c TODO remove this (it's in the LM)
182 @c Replace with more factual directions
183 @ref{Fingering instructions}), you will notice:
184 @quotation
185 @end quotation
186 @c outdated info; probably will delete.
187 @quotation
188 @end quotation
189 @quotation
190 @end quotation
191 @c ode{Fingering_engraver} plug-in will process them.
192 @c I can't figure out what this is supposed to mean.  -gp
193 @c old info?  it doesn't make any sense to me with our current docs.
194 @quotation
195 @end quotation
196 @c ode{Music definitions}
197 @node Layout interfaces
198 @subsection Layout interfaces
199
200 @untranslated
201
202
203 @c index interface, layout
204 @c index layout interface
205 @c index grob
206 @c ode{Fingering} object.  For example, the page says
207 @quotation
208 @c ode{padding} (dimension, in staff space):
209 @c ode{0.5}
210 @end quotation
211 @quotation
212 @end quotation
213 @node Determining the grob property
214 @subsection Determining the grob property
215
216 @untranslated
217
218
219 @c TODO remove this (it's in the LM)
220 @c Replace with more factual directions
221 @quotation
222 @c ode{side-position-interface}
223 @end quotation
224 @c index padding
225 @quotation
226 @end quotation
227 @quotation
228 @end quotation
229 @node Naming conventions
230 @subsection Naming conventions
231
232 @untranslated
233
234
235 @node Modifying properties
236 @section Modifying properties
237
238 @untranslated
239
240
241 @c TODO change the menu and subsection node names to use
242 @c backslash once the new macro to handle the refs
243 @c is available.  Need to find and change all refs at
244 @c the same time. -td
245 @menu
246 * Overview of modifying properties::
247 * The set command::
248 * The override command::
249 * The tweak command::
250 * set versus override::
251 @end menu
252
253 @node Overview of modifying properties
254 @subsection Overview of modifying properties
255
256 @untranslated
257
258
259 @c ode{Stem} or @code{NoteHead}, and @var{property} is an internal
260 @c ode{\once} applies the change during one timestep only.
261 @c ode{Beam} comes after the Beam is started, so it has no effect.
262 @c ode{\revert} in the next example does not do anything.
263 @c leave this as a long long
264 @node The set command
265 @subsection The @code{\set} command
266
267 @untranslated
268
269
270 @c index properties
271 @c index changing properties
272 @c ode{Lyrics}) is used.  In this example,
273 @c ode{Voice}s in the current stave.  The change is applied
274 @c index \once
275 @node The override command
276 @subsection The @code{\override} command
277
278 @untranslated
279
280
281 @c index internal documentation
282 @c index finding graphical objects
283 @c index graphical object descriptions
284 @c index tweaking
285 @c index internal documentation
286 @node The tweak command
287 @subsection The @code{\tweak} command
288
289 @untranslated
290
291
292 @c index tweaking
293 @c index chord, modifying one note in
294 @c ode{ChordEvent} event before the note, so separating the tweak
295 @c ode{ChordEvent} in the music stream, so remaining adjacent to the
296 @c TODO expand to include any further uses of \tweak
297 @c TODO add examples of these
298 @c ode{\tweak} command in the input stream by the automatic
299 @ref{Displaying music expressions}.
300 @c index tweaks in a variable
301 @c index tweaks in lyrics
302 @c index tweaking control points
303 @c index control points, tweaking
304 @node set versus override
305 @subsection @code{\set} vs. @code{\override}
306
307 @untranslated
308
309
310 @c ode{\override}.  There are actually two different kinds of
311 @c ode{studlyCaps}.  They mostly control the translation from
312 @c ode{measurePosition} is an obvious example of
313 @c ode{\override} is actually a shorthand;
314 @c leave this long line -gp
315 @c ode{dashed-words}.  The values of grob properties change
316 @c ode{fontSize} is a special property: it is equivalent to
317 @node Useful concepts and properties
318 @section Useful concepts and properties
319
320 @untranslated
321
322
323 @menu
324 * Input modes::
325 * Direction and placement::
326 * Context layout order::
327 * Distances and measurements::
328 * Staff symbol properties::
329 * Spanners::
330 * Visibility of objects::
331 * Line styles::
332 * Rotating objects::
333 @end menu
334
335 @node Input modes
336 @subsection Input modes
337
338 @untranslated
339
340
341 @ref{Chord notation}.  Chords are rendered as notes on a staff.
342 @ref{Basic percussion notation}.
343 @ref{Entering figured bass}.
344 @ref{Default tablatures}.
345 @ref{Automatic fret diagrams} or you can enter them as a markup
346 @ref{Fret diagram markups}).
347 @c ode{\lyricsto} command which associates the following lyrics
348 @ref{Text markup commands}.
349 @c silly work-around for texinfo broken-ness
350 @c (@strong{Note...} causes a spurious cross-reference in Info)
351 @c ode{\notemode} command.  Input is interpreted as pitches,
352 @node Direction and placement
353 @subsection Direction and placement
354
355 @untranslated
356
357
358 @c TODO Add table showing these
359 @c ode{DOWN} may be used instead of @code{1} and @code{-1}
360 @c ode{direction} to @code{0} or @code{CENTER}.  Alternatively,
361 @c ode{\xxxUp}, @code{xxxDown}, @code{xxxNeutral}
362 @c ode{1} or @code{RIGHT} means @qq{to the right}.  @code{0}
363 @node Context layout order
364 @subsection Context layout order
365
366 @untranslated
367
368
369 @c index contexts, layout order
370 @node Distances and measurements
371 @subsection Distances and measurements
372
373 @untranslated
374
375
376 @c index distances, absolute
377 @c index distances, scaled
378 @c ode{\in}@tie{}(inches), or @code{\pt}@tie{}(points, 1/72.27
379 @c ode{\staff-space} to the quantity.
380 @c ode{StaffSymbol}.  Scaled distances automatically scale with any
381 @c ode{staff-space} property of @code{StaffSymbol}, but fonts scale
382 @c ode{staff-space} property of @code{StaffSymbol} and the size of
383 @c ode{staff-space}.  For an explanation and an example of its use,
384 @ref{Page formatting},
385 @ref{Setting the staff size}.
386 @node Staff symbol properties
387 @subsection Staff symbol properties
388
389 @untranslated
390
391
392 @c index adjusting staff symbol
393 @c index drawing staff symbol
394 @c index staff symbol, setting of
395 @c TODO Extend or remove this section.  See also NR 1.6.2 Staff symbol
396 @c Need to think of uses for these properties.  Eg 'line-positions
397 @c is used in a snippet to thicken centre line.
398 @c If retained, add @ref to here in 1.6.2  -td
399 @c ode{'line-count} property.  The number of staff lines is
400 @node Spanners
401 @subsection Spanners
402
403 @untranslated
404
405
406 @unnumberedsubsubsec Using the @code{spanner-interface}
407 @c ode{minimum-length} property.  Increasing this usually has the
408 @c ode{springs-and-rods} property is set:
409 @c ode{to-barline}.  By default this is true, causing hairpins and
410 @unnumberedsubsubsec Using the @code{line-spanner-interface}
411 @c ode{ly:line-interface::print}.  This routine determines the
412 @c ode{right} sub-lists of the @code{bound-details} property
413 @c ode{LEFT}) makes the line start/end at the left side of the note
414 @c ode{Y} sub-properties.  Setting either @code{stencil-align-dir-y}
415 @c ode{DOWN} means align the @emph{bottom} edge of the text with
416 @node Visibility of objects
417 @subsection Visibility of objects
418
419 @untranslated
420
421
422 @c index objects, visibility of
423 @c index grobs, visibility of
424 @c index visibility of objects
425 @c ode{break-visibility} property can be overridden.  The first
426 @menu
427 * Removing the stencil::
428 * Making objects transparent::
429 * Painting objects white::
430 * Using break-visibility::
431 * Special considerations::
432 @end menu
433
434 @node Removing the stencil
435 @unnumberedsubsubsec Removing the stencil
436
437 @untranslated
438
439
440 @c index stencil, removing
441 @c ode{\revert}.
442 @node Making objects transparent
443 @unnumberedsubsubsec Making objects transparent
444
445 @untranslated
446
447
448 @c index transparent, making objects
449 @node Painting objects white
450 @unnumberedsubsubsec Painting objects white
451
452 @untranslated
453
454
455 @c index objects, coloring
456 @c index coloring objects
457 @c index layers
458 @c index printing order
459 @c index overwriting objects
460 @c index objects, overwriting
461 @c index grobs, overwriting
462 @c ode{1}, although a few objects, including @code{StaffSymbol} and
463 @c ode{BarLine}, are assigned a value of @code{0}.  The order of
464 @c ode{layer} value @code{0}), so overwriting them.  To change this,
465 @c ode{layer}, say @code{-1}, so that it is drawn earlier:
466 @node Using break-visibility
467 @unnumberedsubsubsec Using break-visibility
468
469 @untranslated
470
471
472 @c TODO Add making other objects breakable
473 @c index break-visibility
474 @c ode{break-visibility} property to control their visibility
475 @c Leave this ref on a newline - formats incorrectly otherwise -td
476 @c omit Ambitus as it appears not to be affected by break-visibility -td
477 @c @item @code{Ambitus}          @tab as specified   @tab @code{begin-of-line-visible}
478 @c omit the following item until it can be explained -td
479 @c @item @code{BreakAlignGroup}  @tab @code{Score}          @tab calculated
480 @c omit KeyCancellation until it can be explained -td
481 @c @item @code{KeyCancellation}  @tab ??             @tab @code{begin-of-line-invisible}
482 @c omit LeftEdge until it can be explained -td
483 @c @item @code{LeftEdge}         @tab @code{Score}          @tab @code{center-invisible}
484 @c ode{break-visibility} must be present, not all of them are
485 @node Special considerations
486 @unnumberedsubsubsec Special considerations
487
488 @untranslated
489
490
491 @c index key signature, visibility following explicit change
492 @c index explicitKeySignatureVisibility
493 @c index clef, visibility following explicit change
494 @c index explicitClefVisibility
495 @c ode{explicitClefVisibility} properties.  These are the equivalent
496 @c ode{break-visibility}.  Both are properties of the Staff context,
497 @c ode{\set} command.  Both are set by default to @code{all-visible}.
498 @c ode{break-visibility} must still be overridden in the appropriate
499 @c TODO Add visibility of cautionary accidentals before notes
500 @c index automaticBars
501 @c index bar lines, suppressing
502 @c TODO Add example
503 @c index octavated clefs, visibility of
504 @c index visibility of octavated clefs
505 @c index clefs, visibility of octavation
506 @c ode{OctavateEight} layout object.  Its visibility is controlled
507 @node Line styles
508 @subsection Line styles
509
510 @untranslated
511
512
513 @c ode{ly:line-interface::print}.  This routine determines the
514 @c FIXME Complete
515 @c ode{left} instead of @code{right}.
516 @ref{Spanners}.
517 @node Rotating objects
518 @subsection Rotating objects
519
520 @untranslated
521
522
523 @menu
524 * Rotating layout objects::
525 * Rotating markup::
526 @end menu
527
528 @node Rotating layout objects
529 @unnumberedsubsubsec Rotating layout objects
530
531 @untranslated
532
533
534 @c index rotating objects
535 @c index objects, rotating
536 @c index hairpins, angled
537 @c index angled hairpins
538 @node Rotating markup
539 @unnumberedsubsubsec Rotating markup
540
541 @untranslated
542
543
544 @c ode{outside-staff-priority} property for text is set to @code{#f}
545 @node Advanced tweaks
546 @section Advanced tweaks
547
548 @untranslated
549
550
551 @menu
552 * Aligning objects::
553 * Vertical grouping of grobs::
554 * Modifying stencils::
555 * Modifying shapes::
556 @end menu
557
558 @ref{Explaining the Internals Reference},
559 @ref{Modifying properties},
560 @ref{Interfaces for programmers}.
561 @node Aligning objects
562 @subsection Aligning objects
563
564 @untranslated
565
566
567 @c ode{X-offset} and @code{Y-offset} properties.  The value of
568 @c ode{X-offset} gives the displacement from the x coordinate of
569 @c ode{Y-offset} gives the displacement from the center line of the
570 @c ode{Y-offset} may be set directly or may be set to be calculated
571 @c ode{self-alignment-interface}.}
572 @c ode{X-offset} have no effect.
573 @menu
574 * Setting @code{X-offset} and @code{Y-offset} directly::
575 * Using the @code{side-position-interface}::
576 * Using the @code{self-alignment-interface}::
577 * Using the @code{break-alignable-interface}::
578 @end menu
579
580 @node Setting @code{X-offset} and @code{Y-offset} directly
581 @unnumberedsubsubsec Setting @code{X-offset} and @code{Y-offset} directly
582
583 @untranslated
584
585
586 @c TODO write more
587 @node Using the @code{side-position-interface}
588 @unnumberedsubsubsec Using the @code{side-position-interface}
589
590 @untranslated
591
592
593 @c TODO add an example of each to the table
594 @c TODO Add examples
595 @node Using the @code{self-alignment-interface}
596 @unnumberedsubsubsec Using the @code{self-alignment-interface}
597
598 @untranslated
599
600
601 @c ode{self-alignment-interface} is controlled by the value of
602 @c ode{X-offset} property is set to
603 @c ode{ly:self-alignment-interface::x-aligned-on-self}.
604 @c ode{self-alignment-X}  may be given any
605 @c ode{CENTER} and @code{RIGHT} may be used instead of the values
606 @c ode{-1, 0, 1} respectively.
607 @c ode{ly:self-alignment-interface::y-aligned-on-self}.  However,
608 @c ode{CENTER}, @code{UP} may be substituted for @code{-1, 0, 1}
609 @unnumberedsubsubsec Using the @code{aligned-on-parent} procedures
610 @c Cannot document as they do not seem to operate consistently on all objects -td
611 @c TODO investigate further
612 @c TODO Add example
613 @unnumberedsubsubsec Using the @code{centered-on-parent} procedures
614 @c Cannot document as they do not seem to operate consistently on all objects -td
615 @c TODO investigate further
616 @c TODO The align-interface, BassFigureAlignment and VerticalAlignment
617 @node Using the @code{break-alignable-interface}
618 @unnumberedsubsubsec Using the @code{break-alignable-interface}
619
620 @untranslated
621
622
623 @c index align to objects
624 @c index break-align-symbols
625 @c ode{breathing-sign}, @code{clef}, @code{custos}, @code{staff-bar},
626 @c ode{left-edge}, @code{key-cancellation}, @code{key-signature}, and
627 @c ode{time-signature}.
628 @node Vertical grouping of grobs
629 @subsection Vertical grouping of grobs
630
631 @untranslated
632
633
634 @c FIXME Expand this section
635 @node Modifying stencils
636 @subsection Modifying stencils
637
638 @untranslated
639
640
641 @c ode{MultiMeasureRest} object is @code{ly:multi-measure-rest::print}.
642 @c ode{stencil} property to reference a different, specially-written,
643 @c ode{text} property to the object which is set to contain the
644 @ref{Graphic notation inside markup}.
645 @c ode{\musicglyph} markup command -- see @ref{The Feta font}.
646 @c TODO Add inserting eps files or ref to later
647 @c TODO Add inserting Postscript or ref to later
648 @ref{Graphic notation inside markup},
649 @ref{Formatting text},
650 @ref{Text markup commands},
651 @ref{The Feta font}.
652 @node Modifying shapes
653 @subsection Modifying shapes
654
655 @untranslated
656
657
658 @menu
659 * Modifying ties and slurs::
660 @end menu
661
662 @node Modifying ties and slurs
663 @unnumberedsubsubsec Modifying ties and slurs
664
665 @untranslated
666
667
668 @c index slurs, modifying
669 @c index ties, modifying
670 @c index Bézier curves
671 @c index Bézier control points
672
673 @c -- SKELETON FILE --