Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(362)

Side by Side Diff: Documentation/notation/changing-defaults.itely

Issue 319150043: Issue 3830: Document \offset command
Patch Set: diagram syntax, other improvements Created 7 years, 2 months ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
View unified diff | Download patch
« no previous file with comments | « no previous file | no next file » | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
1 @c -*- coding: utf-8; mode: texinfo; -*- 1 @c -*- coding: utf-8; mode: texinfo; -*-
2 2
3 @ignore 3 @ignore
4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH 4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
5 5
6 When revising a translation, copy the HEAD committish of the 6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. For details, see the Contributors' 7 version that you are working on. For details, see the Contributors'
8 Guide, node Updating translation committishes.. 8 Guide, node Updating translation committishes..
9 @end ignore 9 @end ignore
10 10
(...skipping 1807 matching lines...) Expand 10 before | Expand all | Expand 10 after
1818 @c backslash once the new macro to handle the refs 1818 @c backslash once the new macro to handle the refs
1819 @c is available. Need to find and change all refs at 1819 @c is available. Need to find and change all refs at
1820 @c the same time. -td 1820 @c the same time. -td
1821 1821
1822 @menu 1822 @menu
1823 * Overview of modifying properties:: 1823 * Overview of modifying properties::
1824 * The set command:: 1824 * The set command::
1825 * The override command:: 1825 * The override command::
1826 * The tweak command:: 1826 * The tweak command::
1827 * set versus override:: 1827 * set versus override::
1828 * The offset command::
1828 * Modifying alists:: 1829 * Modifying alists::
1829 @end menu 1830 @end menu
1830 1831
1831 1832
1832 @node Overview of modifying properties 1833 @node Overview of modifying properties
1833 @subsection Overview of modifying properties 1834 @subsection Overview of modifying properties
1834 1835
1835 Each context is responsible for creating certain types of graphical 1836 Each context is responsible for creating certain types of graphical
1836 objects. The settings used for printing these objects are also stored by 1837 objects. The settings used for printing these objects are also stored by
1837 context. By changing these settings, the appearance of objects can be 1838 context. By changing these settings, the appearance of objects can be
(...skipping 659 matching lines...) Expand 10 before | Expand all | Expand 10 after
2497 @funindex \tweak 2498 @funindex \tweak
2498 @funindex \overrideProperty 2499 @funindex \overrideProperty
2499 2500
2500 The commands @code{\tweak} and @code{\overrideProperty} change grob 2501 The commands @code{\tweak} and @code{\overrideProperty} change grob
2501 properties by bypassing all context properties completely and, instead, 2502 properties by bypassing all context properties completely and, instead,
2502 catch grobs as they are being created, setting properties on them for 2503 catch grobs as they are being created, setting properties on them for
2503 a music event (@code{\tweak}) or, in the case of 2504 a music event (@code{\tweak}) or, in the case of
2504 @code{\overrideProperty} for a specific override. 2505 @code{\overrideProperty} for a specific override.
2505 2506
2506 2507
2508 @node The offset command
2509 @subsection The @code{\offset} command
2510
2511 @funindex \offset
2512 @cindex offsetting
2513 @cindex defaults, offsetting
2514
2515 While it is possible to set grob properties to new values with the
2516 @code{\override}, @code{\tweak}, and @code{\overrideProperty} commands,
2517 it is often more convenient to modify such properties relative to a
2518 default value. The @code{\offset} command is available for this
2519 purpose.
2520
2521 The syntax for @code{\offset} is
2522
2523 @example
2524 [-]\offset @var{property} @var{offsets} @var{item}
2525 @end example
2526
2527 The command works by adding the contents of @var{offsets} to the
2528 default setting of the property @var{property} of the grob indicated by
2529 @var{item}.
2530
2531 Depending on the formulation of the command, @code{\offset} may act
2532 as either a @code{\tweak} or @code{\override}. The variations in
2533 usage are discussed after consideration is given to grob properties
2534 that may be used with @code{\offset}.
2535
2536 @subsubsubheading{Properties which may be offset}
2537
2538 Many, but not all, grob properties may be offset. If @var{property}
2539 cannot be offset, the object will remain unchanged and a warning will
2540 be issued. In such cases, @code{\override} or @code{\tweak} should be
2541 used to modify the object instead.
2542
2543 One can work by trial and error and let the warnings be the guide to
2544 what may or may not be offset. A more systematic approach is possible,
2545 however.
2546
2547 The following criteria determine whether a property can be modified with
2548 @code{\offset}:
2549
2550 @itemize
2551
2552 @item
2553 The property has a @q{default setting} in the grob's description. Such
2554 properties are listed for each grob in @rinternals{All layout objects}.
2555 (They are also found in @file{scm/define-grobs.scm}.)
2556
2557 @item
2558 The property takes a numerical value. Numerical values include
2559 @code{number}, list of @code{number}s, @code{number-pair}, and
2560 @code{number-pair-list}. The pages at @rinternals{All layout objects}
2561 list the type of data characteristic to each property. It is immaterial
2562 whether the default setting is a function.
2563
2564 @item
2565 The property cannot be a @q{subproperty}---a property residing within
2566 another property.
2567
2568 @item
2569 Properties set to infinite values cannot be offset. There is no
2570 sensible way to offset positive and negative infinity.
2571 @end itemize
2572
2573 The following examples consider several grob properties against the
2574 criteria outlined above.
2575
2576 @itemize
2577
2578 @item Properties that may be offset
2579
2580 @table @asis
2581
2582 @item @code{Hairpin.height}
2583
2584 This property is not a subproperty, and it is listed at
2585 @rinternals{Hairpin}. For a value, it takes @q{dimension, in staff
2586 space} set to @code{0.6666}---clearly a non-infinite @code{number}.
2587
2588 @item @code{Arpeggio.positions}
2589
2590 The page @rinternals{Arpeggio} lists a @code{positions} property which
2591 accepts a @q{pair of numbers}. It defaults to
2592 @code{ly:arpeggio::positions}---a callback which will be evaluated
2593 during the typesetting phase to yield a pair of numbers for any given
2594 @code{Arpeggio} object.
2595
2596 @end table
2597
2598 @item Properties that may not be offset
2599
2600 @table @asis
2601
2602 @item @code{Hairpin.color}
2603
2604 There is no listing for @code{color} at @rinternals{Hairpin}.
2605
2606 @item @code{Hairpin.circled-tip}
2607
2608 The listing for @code{Hairpin.circled-tip} at @rinternals{Hairpin} shows
2609 that it takes a @code{boolean} value. Booleans are non-numerical.
2610
2611 @item @code{Stem.details.lengths}
2612
2613 Though listed at @rinternals{Stem} and defaulting to a list of
2614 @code{number}s, this is a @q{subproperty}. There is currently no
2615 support for @q{nested properties}.
2616
2617 @end table
2618
2619 @end itemize
2620
2621 @subsubsubheading{@bs{}offset as an override}
2622
2623 If @var{item} is a grob name like @code{Arpeggio} or
2624 @code{Staff.OttavaBracket}, the result is an @code{\override} of the
2625 specified grob-type.
2626
2627 @example
2628 \offset @var{property} @var{offsets} [@var{context}.]@var{GrobName}
2629 @end example
2630
2631 Note that the leading hyphen is @emph{never} used with the @q{override}
2632 form, just as it is never used with the @code{\override} command itself.
2633
2634 The following example uses the @q{override} form to lengthen the
2635 default arpeggios shown in the first measure to cover the extent of
2636 the chords more fully. The arpeggios are stretched by a half
2637 staff-space to top and bottom. Also shown is the same operation done on
2638 the first chord with an ordinary override of the @code{positions}
2639 property. This method is not at all expressive of the task of
2640 @q{stretching by a half staff-space}, as the endpoints must be specified
2641 with absolute rather than relative coordinates. Furthermore, individual
2642 overrides would be needed for the other chords, as they vary in size and
2643 position.
2644
2645 @lilypond[quote,verbatim]
2646 arpeggioMusic = {
2647 <c' e' g'>\arpeggio <a' c'' e''>\arpeggio
2648 <d' f' a' c''>\arpeggio <c' e' g' b' d'' f'' a''>\arpeggio
2649 }
2650
2651 {
2652 \arpeggioMusic
2653 \bar "||"
2654 \offset positions #'(-0.5 . 0.5) Arpeggio
2655 \arpeggioMusic
2656 \bar "||"
2657 \once \override Arpeggio.positions = #'(-3.5 . -0.5)
2658 <c' e' g'>1\arpeggio
2659 \bar "||"
2660 }
2661 @end lilypond
2662
2663 In its @q{override} usage, @code{\offset} may be prefaced with
2664 @code{\once} or @code{\temporary} and reverted using @code{\revert} with
2665 @var{property}. This follows from the fact that @code{\offset} actually
2666 creates an @code{\override} of @var{property}.
2667
2668 @lilypond[quote,verbatim]
2669 music = { c'8\< d' e' f'\! }
2670
2671 {
2672 \music
2673 \offset height 1 Hairpin
2674 \music
2675 \music
2676 \revert Hairpin.height
2677 \music
2678 \bar "||"
2679 \once \offset height 1 Hairpin
2680 \music \music
2681 \bar "||"
2682 \override Hairpin.height = 0.2
2683 \music
2684 \temporary \offset height 2 Hairpin
2685 \music
2686 \music
2687 \revert Hairpin.height
2688 \music
2689 \bar "||"
2690 }
2691 @end lilypond
2692
2693 Also like @code{\override}, the @q{override} form of @code{\offset} may
2694 be used with @code{\undo} and @code{\single}.
2695
2696 @lilypond[quote,verbatim]
2697 longStem = \offset length 6 Stem
2698
2699 {
2700 \longStem c'4 c''' c' c''
2701 \bar "||"
2702 \undo \longStem c'4 c''' c' c''
2703 \bar "||"
2704 \single \longStem c'4 c''' c' c''
2705 \bar "||"
2706 }
2707 @end lilypond
2708
2709 @subsubsubheading{@bs{}offset as a tweak}
2710
2711 If @var{item} is a music expression such as @code{(} or
2712 @code{\arpeggio}, the result is the same music expression with a tweak
2713 applied.
2714
2715 @example
2716 [-]\offset [@var{GrobName}.]@var{property} @var{offsets} @var{music-expression}
2717 @end example
2718
2719 The syntax of @code{\offset} in its @q{tweak} form is analogous to the
2720 @code{\tweak} command itself, both in ordering and in the presence or
2721 absence of the leading hyphen.
2722
2723 The following example uses the @q{tweak} form to adjust the vertical
2724 position of the @code{BreathingSign} object. Compare this with the
2725 ordinary @code{\tweak} command also demonstrated. The syntax is
2726 equivalent; however, the output of @code{\tweak} is less intuitive,
2727 since @code{BreathingSign.Y-offset} is calculated from the middle
2728 staff-line. It is not necessary to know how @code{Y-offset} is
2729 calculated when using @code{\offset}.
2730
2731 @lilypond[quote,verbatim]
2732 {
2733 c''4
2734 \breathe
2735 c''4
2736 \offset Y-offset 2 \breathe
2737 c''2
2738 \tweak Y-offset 3 \breathe
2739 }
2740 @end lilypond
2741
2742 In the previous example, the tweaked objects were created directly from
2743 the user input: the @code{\breathe} command was an explicit instruction
2744 to return a @code{BreathingSign} object. Since the focus of the command
2745 was unambiguous, there was no need to specify the object's name. When
2746 an object is @emph{indirectly} created, however, it is necessary to
2747 include the grob's name. This is the same as for the @code{\tweak}
2748 command.
2749
2750 In the following example, the @code{Beam} object is lowered two
2751 staff-spaces by applying @code{\offset} to the @code{positions}
2752 property.
2753
2754 The first application of @code{\offset} requires that the grob's name
2755 be included, because nothing in the input explicitly creates the
2756 beam. In the second application, the beam is created manually with the
2757 music expression @code{[}; therefore, the grob's name is not needed.
2758 (Also illustrated is a shorthand: a single @code{number} will be applied
2759 to both members of a @code{number-pair}.)
2760
2761 @lilypond[quote,verbatim]
2762 {
2763 c''8 g'' e'' d''
2764 \offset Beam.positions #'(-2 . -2)
2765 c''8 g'' e'' d''
2766 c''8 g'' e'' d''
2767 c''8-\offset positions #-2 [ g'' e'' d'']
2768 }
2769 @end lilypond
2770
2771 @subsubsubheading{@bs{}offset with broken spanners}
2772
2773 Independently modifying segments of a spanner extending over a line
2774 break or breaks is also possible. In this case, @var{offsets}
2775 takes a list of values of the property's required data type.
2776
2777 The @code{\offset} command used in this manner is similiar to the
simon.albrecht 2017/01/25 22:33:32 s/similiar/similar
david.nalesnik 2017/01/26 14:33:18 Yup--thanks. Will bundle that with whatever chang
2778 @code{\alterBroken} command. (See @ref{Modifying broken spanners}.)
2779 In contrast with @code{\alterBroken}, however, the values given to
2780 @code{\offset} are relative, not absolute.
2781
2782 The following example displaces the @q{broken} @code{OttavaBracket}
2783 object through its @code{staff-padding} property. Since the property
2784 takes a @code{number}, @var{offsets} is provided with a list of
2785 @code{number}s to account for the two segments created by the line
2786 break. The slur piece on the first line is effectively untouched since
2787 @code{0} is added to its default value. The segment on the second
2788 line is raised two staff-spaces from its default height. The default
2789 height happens to be @code{2}, though it is not necesssary to know this.
2790
2791 @lilypond[quote,verbatim]
2792 {
2793 \offset staff-padding #'(0 3) Staff.OttavaBracket
2794 \ottava #1
2795 c'''2 c'''
2796 \break
2797 c'''2 c'''
2798 }
2799 @end lilypond
2800
2801 The following example mimics the effect of the @code{\shape} command by
2802 offsetting the @code{control-points} property of the @code{Slur} object.
2803 Here, @var{offsets} is a list of @code{number-pair-list}s, one for each
2804 slur segment. This example achieves a result identical to the
2805 corresponding illustration at @ref{Modifying shapes}.
2806
2807 @lilypond[quote,verbatim]
2808 {
2809 c'4-\offset control-points #'(
2810 ((0 . 0) (0 . 0) (0 . 0) (0 . 1))
2811 ((0.5 . 1.5) (1 . 0) (0 . 0) (0 . -1.5))
2812 ) ( f'4 g' c''
2813 \break
2814 d'4 c'' f' c')
2815 }
2816 @end lilypond
2817
2818
2507 @node Modifying alists 2819 @node Modifying alists
2508 @subsection Modifying alists 2820 @subsection Modifying alists
2509 2821
2510 Some user-configurable properties are internally represented as 2822 Some user-configurable properties are internally represented as
2511 @emph{alists} (association lists), which store pairs of 2823 @emph{alists} (association lists), which store pairs of
2512 @emph{keys} and @emph{values}. The structure of an alist is: 2824 @emph{keys} and @emph{values}. The structure of an alist is:
2513 2825
2514 @example 2826 @example
2515 '((@var{key1} . @var{value1}) 2827 '((@var{key1} . @var{value1})
2516 (@var{key2} . @var{value2}) 2828 (@var{key2} . @var{value2})
(...skipping 2351 matching lines...) Expand 10 before | Expand all | Expand 10 after
4868 5180
4869 \relative { 5181 \relative {
4870 \tempo \markup { "Low tempo" } 5182 \tempo \markup { "Low tempo" }
4871 c''4 d e f g1 5183 c''4 d e f g1
4872 \tempoPadded #4.0 "High tempo" 5184 \tempoPadded #4.0 "High tempo"
4873 g4 f e d c1 5185 g4 f e d c1
4874 } 5186 }
4875 @end lilypond 5187 @end lilypond
4876 5188
4877 @c TODO: add appropriate @@ref's here. 5189 @c TODO: add appropriate @@ref's here.
OLDNEW
« no previous file with comments | « no previous file | no next file » | no next file with comments »

Powered by Google App Engine
RSS Feeds Recent Issues | This issue
This is Rietveld f62528b