1 \input texinfo @c -*- coding: utf-8; mode: texinfo; documentlanguage: nl -*-
2 @c This file is part of notation.tely
4 Translation of GIT committish: 1b3da70d81938d19a2b107382bbe25a267cf130b
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..
12 @c -*- coding: utf-8; mode: texinfo; -*-
14 @node Changing defaults
15 @chapter Changing defaults
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
24 * Interpretation contexts::
25 * Explaining the Internals Reference::
26 * Modifying properties::
27 * Useful concepts and properties::
31 @node Interpretation contexts
32 @section Interpretation contexts
38 * Contexts explained::
40 * Keeping contexts alive::
41 * Modifying context plug-ins::
42 * Changing context default settings::
43 * Defining new contexts::
47 @node Contexts explained
48 @subsection Contexts explained
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
58 * Score - the master of all contexts::
59 * Top-level contexts - staff containers::
60 * Intermediate-level contexts - staves::
61 * Bottom-level contexts - voices::
64 @node Score - the master of all contexts
65 @unnumberedsubsubsec Score - the master of all contexts
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
77 @node Intermediate-level contexts - staves
78 @unnumberedsubsubsec Intermediate-level contexts - staves
83 @c ode{Voice} contexts.
84 @node Bottom-level contexts - voices
85 @unnumberedsubsubsec Bottom-level contexts - voices
90 @node Creating contexts
91 @subsection Creating contexts
96 @c TODO \new Score and \score
97 @c TODO more complete descriptions rather than learning style
99 @c index Context, creating
100 @c ode{Voice}). This command creates a new context, and starts
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
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
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
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
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
158 @c TODO Better example needed. Ref LM, and expand on it.
160 @c index nested contexts
161 @c index contexts, nested
162 @node Explaining the Internals Reference
163 @section Explaining the Internals Reference
169 * Navigating the program reference::
170 * Layout interfaces::
171 * Determining the grob property::
172 * Naming conventions::
175 @node Navigating the program reference
176 @subsection Navigating the program reference
181 @c TODO remove this (it's in the LM)
182 @c Replace with more factual directions
183 @ref{Fingering instructions}), you will notice:
186 @c outdated info; probably will delete.
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.
196 @c ode{Music definitions}
197 @node Layout interfaces
198 @subsection Layout interfaces
203 @c index interface, layout
204 @c index layout interface
206 @c ode{Fingering} object. For example, the page says
208 @c ode{padding} (dimension, in staff space):
213 @node Determining the grob property
214 @subsection Determining the grob property
219 @c TODO remove this (it's in the LM)
220 @c Replace with more factual directions
222 @c ode{side-position-interface}
229 @node Naming conventions
230 @subsection Naming conventions
235 @node Modifying properties
236 @section Modifying properties
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
246 * Overview of modifying properties::
248 * The override command::
249 * The tweak command::
250 * set versus override::
253 @node Overview of modifying properties
254 @subsection Overview of modifying properties
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
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
275 @node The override command
276 @subsection The @code{\override} command
281 @c index internal documentation
282 @c index finding graphical objects
283 @c index graphical object descriptions
285 @c index internal documentation
286 @node The tweak command
287 @subsection The @code{\tweak} command
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}
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
325 * Direction and placement::
326 * Context layout order::
327 * Distances and measurements::
328 * Staff symbol properties::
330 * Visibility of objects::
336 @subsection Input modes
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
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
369 @c index contexts, layout order
370 @node Distances and measurements
371 @subsection Distances and measurements
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
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
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
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
427 * Removing the stencil::
428 * Making objects transparent::
429 * Painting objects white::
430 * Using break-visibility::
431 * Special considerations::
434 @node Removing the stencil
435 @unnumberedsubsubsec Removing the stencil
440 @c index stencil, removing
442 @node Making objects transparent
443 @unnumberedsubsubsec Making objects transparent
448 @c index transparent, making objects
449 @node Painting objects white
450 @unnumberedsubsubsec Painting objects white
455 @c index objects, coloring
456 @c index coloring objects
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
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
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
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
508 @subsection Line styles
513 @c ode{ly:line-interface::print}. This routine determines the
515 @c ode{left} instead of @code{right}.
517 @node Rotating objects
518 @subsection Rotating objects
524 * Rotating layout objects::
528 @node Rotating layout objects
529 @unnumberedsubsubsec Rotating layout objects
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
544 @c ode{outside-staff-priority} property for text is set to @code{#f}
545 @node Advanced tweaks
546 @section Advanced tweaks
553 * Vertical grouping of grobs::
554 * Modifying stencils::
558 @ref{Explaining the Internals Reference},
559 @ref{Modifying properties},
560 @ref{Interfaces for programmers}.
561 @node Aligning objects
562 @subsection Aligning objects
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.
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}::
580 @node Setting @code{X-offset} and @code{Y-offset} directly
581 @unnumberedsubsubsec Setting @code{X-offset} and @code{Y-offset} directly
587 @node Using the @code{side-position-interface}
588 @unnumberedsubsubsec Using the @code{side-position-interface}
593 @c TODO add an example of each to the table
595 @node Using the @code{self-alignment-interface}
596 @unnumberedsubsubsec Using the @code{self-alignment-interface}
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
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}
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
634 @c FIXME Expand this section
635 @node Modifying stencils
636 @subsection Modifying stencils
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},
652 @node Modifying shapes
653 @subsection Modifying shapes
659 * Modifying ties and slurs::
662 @node Modifying ties and slurs
663 @unnumberedsubsubsec Modifying ties and slurs
668 @c index slurs, modifying
669 @c index ties, modifying
670 @c index Bézier curves
671 @c index Bézier control points
673 @c -- SKELETON FILE --